> 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/frontend.md). # Frontend element types The `frontend` section defines all visible elements in a menu. Each key you add under `frontend` serves as that element's unique ID, using `type` to choose the element kind along with position, size, and appearance properties. Click and hover interactions are configured separately in the matching `backend` regions. ## Properties shared by all elements Every frontend element supports these four base transform and visibility properties: | Property | Valid values and description | Default when omitted | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------- | | `offset` | Object with finite numeric `x`, `y`, and `z` values controlling the element's position relative to the canvas center (or parent group center). | `{x: 0, y: 0, z: 0}` | | `rotation` | Object with `x`, `y`, and `z` angles in degrees. `z` rotates within the menu plane; `x` and `y` tilt the element forward or backward. | `{x: 0, y: 0, z: 0}` | | `scale` | Scale multiplier object using non-zero numbers. Flat elements use `x` and `y`; 3D `item` and `block` elements also accept `z`. Negative values mirror the element. | `1` on each axis | | `visible` | `true` (shown) or `false` (hidden). Do not set static `scale` to `0` to hide an element; use `visible: false` instead. | `true` | ## Text (`text`) Displays titles, button labels, or dynamic data powered by placeholders: ```yaml frontend: player-info: type: text content: '&f%player_name%' size: 5 offset: {x: 0, y: 20, z: 1} update: 20 ``` | Property | Valid values and description | Default when omitted | | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | | `content` | Required string. Supports color codes, gradients, `\n` line breaks, and PlaceholderAPI placeholders. | Required | | `size` | Number greater than `0` controlling the font size. | `10` | | `font` | Resource pack font ID formatted as `namespace:path` (lowercase letters, digits, underscores, dots, hyphens, or slashes). | `minecraft:default` | | `opacity` | Integer from `0` to `255` controlling text opacity (`255` is fully opaque). | `255` | | `line-width` | Integer greater than `0` setting the automatic word-wrap width in font pixels. | `200` | | `alignment` | Alignment of multiple lines within the paragraph box: `left`, `center`, or `right`. | `center` | | `update` | Placeholder refresh interval in server ticks. Use a positive integer for periodic updates (such as `20` for roughly once per second) or `-1` to parse only once when the menu opens. Cannot be `0`. | `-1` | **Tip on text positioning and alignment**: `offset` always positions the **center of the entire text block**, while `alignment` controls how lines of different lengths align relative to each other inside a multi-line paragraph. If your text is only a single line, `left`, `center`, and `right` will appear in the exact same spot. To move a text element left or right on the canvas, adjust `offset.x`. ## Rectangles, borders and lines (`rectangle` / `frame` / `line`) These three geometric primitives let you build clean UI panels, button backgrounds, and dividers directly in YAML without creating external image assets. All three share two appearance properties: * `color`: Quoted 6-digit hex color string formatted as `'#RRGGBB'`. Defaults to `'#FFFFFF'` (white). * `opacity`: Integer from `0` to `255` controlling opacity. Defaults to `255`. | Type (`type`) | Dimension properties and requirements | Common uses | | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | | `rectangle` | `width` and `height`, both numbers greater than `0`. | Panel backgrounds, card fills, button color blocks. | | `frame` | `width` (outer width), `height` (outer height), and `thickness` (border thickness, default `1`). All three must be greater than `0` and satisfy **`2 * thickness < min(width, height)`**. | Window outlines, selection highlight borders. | | `line` | `width` (length) and `thickness` (line weight), both numbers greater than `0`. Combine with `rotation: {z: 90}` for a vertical line. | Title underlines, section dividers. | ```yaml frontend: panel: type: rectangle width: 140 height: 80 color: '#182031' opacity: 235 panel-border: type: frame width: 140 height: 80 thickness: 1 color: '#617DA0' offset: {z: 1} divider: type: line width: 100 thickness: 1 color: '#617DA0' offset: {y: 10, z: 1} ``` **Note on border thickness**: A `frame` draws an inward hollow border, so the combined thickness of two opposite sides cannot fill or exceed the total width or height. For example, if you make a very narrow frame with `width: 2`, the default `thickness: 1` fails validation because `1 * 2 >= 2` leaves no hollow interior. Lowering `thickness` (for example, to `0.5`) resolves this: ```yaml frontend: narrow-border: type: frame width: 2 height: 10 thickness: 0.5 ``` When placing a border (`z: 1`) over a panel (`z: 0`) at different depths and wanting their edges to line up cleanly, enable `depth-mode: layered` under `canvas` (see [Canvas, coordinates and screen position](/en/menu-configuration/menus/canvas.md)). ## Images (`image`) Display custom PNG graphics in your menu: ```yaml frontend: logo: type: image source: /ui/logo.png width: 96 height: 32 offset: {z: 1} ``` | Property | Valid values and description | Default when omitted | | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | | `source` | Required PNG file path (aliases `path`, `image`, and `material` are also accepted; use one). Starts with `/` and maps to `plugins/ArcMenu/images/`. | Required | | `width` | Display width on the canvas (number greater than `0`). | Original image pixel width | | `height` | Display height on the canvas (number greater than `0`). | Original image pixel height | | `opacity` | Integer from `0` to `255` controlling opacity. | `255` | | `color` | Tints the image using `'#RRGGBB'` or `'&#RRGGBB'` (great for coloring white icons). | Untinted (original colors) | | `update` | Refresh interval when the path contains placeholders (positive integer ticks, or `-1` for no refresh). | `-1` | Place image files inside `plugins/ArcMenu/images/`, using lowercase letters, digits, underscores (`_`), dots (`.`), or hyphens (`-`) for folder and file names. For example, `images/ui/logo.png` is referenced as `/ui/logo.png`. Image paths also support dynamic placeholders. Setting `source: /ranks/%player_rank%.png` with `update: 20` automatically swaps the displayed rank icon as the player's rank changes. ## Animated GIFs (`gif`) Plays animated GIFs directly on the menu canvas: ```yaml frontend: banner: type: gif source: /ui/banner.gif width: 160 height: 40 speed: 1 ``` `gif` supports all `image` properties (using a `.gif` file placed under `images/`) and adds a `speed` property: * `speed`: Number greater than `0` controlling how many frames advance per game tick. Defaults to `1`. For details on frame splitting and resource pack generation, see [Animated GIFs](/en/feature-configuration/gif.md). ## Items (`item`) Renders vanilla items, player heads, custom model data, or items from third-party plugins (CraftEngine, Nexo, ItemsAdder): ```yaml frontend: sword: type: item material: minecraft:diamond_sword context: GUI scale: {x: 24, y: 24, z: 24} offset: {z: 2} ``` | Property | Valid values and description | Default when omitted | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------- | | `material` | Required string specifying the item material, head tag, or custom item ID. | Required | | `context` | Item display perspective: `GUI`, `HEAD`, `FIXED`, `GROUND`, `NONE`, `FIRSTPERSON_LEFTHAND`, `FIRSTPERSON_RIGHTHAND`, `THIRDPERSON_LEFTHAND`, or `THIRDPERSON_RIGHTHAND`. | `GUI` | | `scale` | Item size controlled by `x`, `y`, and `z` under `scale` (defaults to `1` per axis). Standard menu icons typically use values around `16` to `32` on all three axes. | `{x: 1, y: 1, z: 1}` | ### Supported `material` formats 1. **Vanilla items**: Case-insensitive, accepting either underscores or spaces—for example, `minecraft:diamond_sword`, `diamond_sword`, or `'Cyan Stained Glass Pane'`. 2. **Player heads and custom skull textures**: * Specific player name or UUID: `''` * Current viewer's avatar: `''` (loads immediately for online players; fetches skin data asynchronously for offline players and refreshes the skull automatically once loaded) * Texture hash or Base64 skin value: `''` or `''` 3. **Modifier tags** (append to a vanilla material; multiple tags can be combined): * Custom model data: `'coal'` * Leather armor dye (RGB): `'leather chestplate'` * Banner patterns (layered in order): `'white banner'` * Combined example: `'leather chestplate'` 4. **Third-party custom item plugins**: * **CraftEngine**: Write `namespace:item_id` directly, or prefix explicitly with `craftengine:namespace:item_id` * **Nexo**: Write `nexo:item_id` * **ItemsAdder**: Write `ia:namespace:item_id` or `itemsadder:namespace:item_id` ## Blocks (`block`) Renders 3D block models and their block states directly in the menu: ```yaml frontend: grass: type: block block-data: 'minecraft:grass_block[snowy=false]' rotation: {x: -20, y: 35, z: 0} scale: {x: 24, y: 24, z: 24} offset: {z: 2} ``` * `block-data`: Required string containing a vanilla block ID and optional bracketed block state properties (such as `'minecraft:oak_stairs[facing=north,half=bottom]'`). * Block size is controlled through the `x`, `y`, and `z` axes of `scale`. Adding a slight tilt on `rotation.x` and `rotation.y` produces a clean isometric 3D block icon. ## Groups (`group`) A `group` bundles multiple elements together under `children` and supports multi-level nesting. Moving, rotating, scaling, or hiding a parent group transforms all of its child elements together. For full details on grouping and template reuse, continue to [Groups and reusable templates](/en/menu-configuration/menus/groups-templates.md). --- # 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/frontend.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.