> 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/getting-started/first-menu.md).

# Your first menu

In this guide, we will build a clean menu with a title and a welcome button. When a player opens the menu, points at the button with their crosshair or cursor, and right-clicks, they will receive a personalized welcome message in chat.

## Create the menu file

Open your server's `plugins/ArcMenu/menus/` directory and create a new file named `welcome.yml`.

> **Tip**: If you create a completely empty `welcome.yml` file and run `/arcmenu reload`, ArcMenu will automatically fill in `schema-version`, `id`, and a default `canvas` block based on the filename. Filenames just need to start with a letter or number and use lowercase letters, numbers, underscores, or hyphens.

Paste the following configuration into `welcome.yml` and save it:

```yaml
schema-version: 1
id: welcome

canvas:
  width: 320
  height: 180
  pixels-per-block: 42.7
  distance: 3

frontend:
  background:
    type: rectangle
    width: 140
    height: 80
    color: '#182031'
    opacity: 235
  title:
    type: text
    content: '&fWelcome to the server'
    offset: {y: 24, z: 1}
    size: 5
  description:
    type: text
    content: '&7Right-click the button below'
    offset: {y: 4, z: 1}
    size: 3
  greeting-button:
    type: rectangle
    width: 60
    height: 18
    color: '#365E91'
    offset: {y: -20, z: 1}
  greeting-label:
    type: text
    content: '&fSay hello'
    offset: {y: -20, z: 2}
    size: 4

backend:
  greeting-area:
    x: 0
    y: -20
    width: 60
    height: 18
    actions:
      right:
        - 'tell: &aWelcome, %player_name%!'
```

After saving the file, run `/arcmenu reload` in-game or from the console, then run `/arcmenu open welcome` to see the menu right in front of you. The `welcome` argument in the command matches the `id: welcome` field at the top of the file.

If you have the client editor mod installed, you can also run `/arcmenu edit welcome` in-game to tweak the layout visually and click Save to apply your changes on the spot.

## How the configuration fits together

A standard ArcMenu file is organized into three main sections: canvas settings, frontend visuals, and backend interactions:

* **Metadata and canvas (`canvas`)**: `schema-version` is always `1`, and `id` is the menu's unique identifier. `canvas` sets up a 16:9 screen measuring `320 × 180` logical pixels, while `distance: 3` and `pixels-per-block: 42.7` establish the design reference distance and scale (the actual in-game viewing distance is controlled by `offset.yml`, which defaults to `0.65` blocks in front of the player's eyes and scales the menu automatically so its apparent size matches your design).
* **Frontend visuals (`frontend`)**: Everything the player sees lives here. This example uses `type: rectangle` to draw a dark blue panel (`background`) and a lighter blue button shape (`greeting-button`), using hex colors like `'#182031'` and an `opacity` value from `0` to `255`. It then uses `type: text` to place the title, subtitle, and button label.
* **Backend hitboxes (`backend`)**: Frontend elements only draw the visuals; actual click detection is handled by regions inside `backend`. Here, `greeting-area` defines a `60 × 18` rectangular hitbox centered at `(0, -20)`, sitting directly over the visual button. When a player right-clicks (`right`) inside that box, the `tell:` action sends them the chat message.

Notice how the coordinates line up: `(0, 0)` is the exact center of the canvas, with positive `y` going up and negative `y` going down. The button rectangle (`greeting-button`), button text (`greeting-label`), and backend click region (`greeting-area`) all place their center at `y: -20` (with `x` omitted so it defaults to `0`), stacking them cleanly on top of one another. Whenever you want to move the button, just update `x` and `y` on all three together. On the frontend, `z` controls layer order—higher numbers appear closer to the player, so giving the text `z: 2` keeps it clearly in front of the `z: 1` button background.

## Try a few changes

With this foundation working, you can experiment with a few quick edits:

* Change the text in `content` to update the title (both `&` color codes and MiniMessage tags work), or edit the text after `tell:` to customize the chat reply.
* Replace the action under `actions.right` with `- 'open: main'` so right-clicking the button takes the player straight to the server's `main` menu. See [Actions and navigation](/en/menu-configuration/menus/actions.md) for running commands, charging currency, playing sounds, and more.
* Only one menu on the server can be marked as the main menu (the one opened by pressing **Shift+F**). If you want `welcome` to become your server's main menu, set `main-menu: false` (or remove the line) in your current main menu (`main.yml` by default), add `main-menu: true` at the top level of `welcome.yml`, and reload.

To explore all available properties for menus, continue to [Menu document structure](/en/menu-configuration/menus.md), or head over to [Visual editor](/en/feature-configuration/editor.md) to arrange elements by dragging them directly in-game.


---

# 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/getting-started/first-menu.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.