> 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/canvas.md).

# Canvas, coordinates and screen position

Understanding ArcMenu's coordinate system makes laying out menus straightforward. Whether you write YAML by hand or drag elements around in the visual editor, every element follows the same directional rules:

* **Origin `(0, 0)`** sits at the exact center of the canvas.
* **`x` axis** controls horizontal position: positive values move right, negative values move left.
* **`y` axis** controls vertical position: positive values move up, negative values move down.
* **`z` axis** controls depth: positive values move closer to the player's eyes (in front), and negative values move farther away (behind).

Internal menu layout uses logical canvas units (virtual pixels), while the physical distance between the menu and the player in the game world is measured in Minecraft blocks.

## Canvas configuration (`canvas`)

Each menu's `canvas` section defines the size and proportions of its virtual screen:

```yaml
canvas:
  width: 320
  height: 180
  pixels-per-block: 42.7
  distance: 3
  depth-mode: perspective
```

| Field              | Valid values and description                                                              | Default when omitted |
| ------------------ | ----------------------------------------------------------------------------------------- | -------------------- |
| `width`            | Logical canvas width. Must be a number greater than `0`.                                  | `320`                |
| `height`           | Logical canvas height. Must be a number greater than `0`.                                 | `180`                |
| `pixels-per-block` | Number of canvas units per block length. Must be a number greater than `0`.               | `42.7`               |
| `distance`         | Design reference distance of the menu in blocks. Must be a number greater than `0`.       | `3`                  |
| `depth-mode`       | Depth rendering mode: `perspective` (3D perspective) or `layered` (flat layer alignment). | `perspective`        |

The default `320 × 180` canvas forms a standard 16:9 screen. Because `(0, 0)` is at the center, the left edge is `x: -160`, the right edge is `x: 160`, the top edge is `y: 90`, and the bottom edge is `y: -90`.

To change how large the entire menu appears on screen, adjust `pixels-per-block` or `distance`:

* **Decrease `pixels-per-block`** (for example, to `32`): each canvas unit takes up more space, making the entire menu appear **larger**.
* **Increase `pixels-per-block`** (for example, to `60`): canvas units pack more tightly together, making the entire menu appear **smaller**.
* **Change `distance`**: a larger design distance makes the menu look smaller in the player's view, while a shorter design distance makes it look larger.

Note that `canvas.distance` is the design reference distance used to calculate visual proportions. The actual physical distance at which the menu spawns in front of the player at runtime is controlled by `offset.yml` (which defaults to `0.65` blocks). ArcMenu automatically scales the menu to match that physical distance so your intended visual size stays the same.

## Aligning element coordinates and click regions

Frontend elements set their position inside `offset`, whereas backend click regions use `x` and `y` directly. In both cases, the coordinates specify the **center of the element or region**:

```yaml
frontend:
  button-bg:
    type: rectangle
    width: 60
    height: 18
    color: '#365E91'
    offset: {x: 0, y: -20, z: 1}
  button-label:
    type: text
    content: '&fClose'
    size: 4
    offset: {x: 0, y: -20, z: 2}

backend:
  close-area:
    x: 0
    y: -20
    width: 60
    height: 18
    actions:
      right: close
```

In this example, the background rectangle, text label, and clickable region are all centered at `(0, -20)` with dimensions of `60 × 18` (extending 30 units left and right, and 9 units up and down). Setting the text's `z` to `2` places it closer to the player than the background at `z: 1`, so the label renders cleanly on top of the button background.

When a frontend element is placed inside a `group`, its `offset` becomes relative to the group's center. Whenever you move or scale a frontend button, remember to update the matching `backend` region so the clickable area lines up with the final visual position and size.

## Depth modes: perspective vs. flat layered alignment

When stacking backgrounds, borders, images, and text, you assign different `z` values to control which layer appears in front. `depth-mode` controls how elements at different `z` depths are projected onto the screen:

### `perspective` (default 3D perspective)

Follows natural 3D perspective where closer objects appear larger. Increasing an element's `z` value moves it closer to the player, which makes it look slightly larger on screen and shifts it outward toward the edges of the view. This mode works well for menus designed with a sense of three-dimensional depth.

### `layered` (flat layer alignment)

```yaml
canvas:
  width: 320
  height: 180
  pixels-per-block: 42.7
  distance: 3
  depth-mode: layered
```

For clean, flat 2D interfaces, use `layered` (you can also toggle this directly in the visual editor's canvas settings).

In `layered` mode, `z` values still determine front-to-back stacking order (higher `z` covers lower `z`), but the server automatically compensates for the size changes and positional drift caused by depth differences. A background panel at `z: 1` and a border frame at `z: 2` that both specify `x: 50, y: 30, width: 100, height: 40` will align edge-to-edge on screen. Depth changes coming from groups and animations also receive this automatic compensation.

Keep in mind that `layered` specifically compensates flat interface elements that stay parallel to the menu plane. If you tilt a flat element around the `x` or `y` axis, or place 3D `item` and `block` elements that have their own thickness, they retain their natural 3D perspective. Keep your elements in front of the viewpoint and use small `z` steps (such as `0.5`, `1`, `2`) to separate layers.

## Global screen positioning: `offset.yml`

While `canvas` controls the design dimensions of an individual menu, `plugins/ArcMenu/offset.yml` controls where menus are physically placed in front of the player across the entire server:

```yaml
touch:
  distance: 0.65
  offset: {x: 0, y: 0, z: 0}

mouse:
  distance: 0.65
  offset: {x: 0, y: 0, z: 0}
```

The file has separate sections for `touch` (Touch mode) and `mouse` (which applies to Mouse mode, Vision mode, and visual editor previews):

* **`distance`**: The actual physical distance in blocks from the player's eyes to the menu screen (`0.1` to `16`). Changing this value **does not change how large the menu looks on screen**—ArcMenu automatically rescales the elements to match. It only changes how close the menu entities sit in the world (for example, reducing `distance` helps prevent the menu from clipping into walls right in front of the player).
* **`offset`**: Additional translation of the entire screen in blocks, with valid values from `-16` to `16` on the `x`, `y`, and `z` axes. Positive `x` shifts the screen right, positive `y` shifts it up, and positive `z` pulls it closer to the player.

For instance, if menus feel slightly too low in Touch mode, set `touch.offset.y` to `0.05`, save the file, run `/arcmenu reload`, and reopen the menu to see the updated position.

## Field of view (FOV) behavior across modes

When players adjust their FOV slider in the client settings, each input mode handles the view as follows:

* **Mouse mode**: With the companion resource pack loaded, menus maintain a fixed-FOV display proportion and do not warp when the player sprints or changes their FOV setting.
* **Vision mode and visual editor preview**: Rendered independently by the client at a fixed 70° vertical FOV, keeping the menu size constant on screen and working alongside shader packs.
* **Touch mode**: Rendered purely with vanilla display entities without loading custom shaders, ensuring full compatibility with shader packs. The menu size on screen scales naturally with the player's FOV setting just like ordinary objects in the world.
* **Effect cutscenes**: Use a fixed vanilla camera viewpoint and render according to the scene's own camera design.


---

# 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/canvas.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.