> For the complete documentation index, see [llms.txt](https://simple.superiormc.cn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://simple.superiormc.cn/arcmenu-wiki/menu-configuration/menus/canvas.md).

# Canvas, coordinates and screen placement

Menu layouts use canvas coordinates. Edit a menu file to move an individual element; use screen placement settings to reposition all menus in front of players.

This page covers `canvas`, layout coordinates and overall screen placement in that order. See [Menu document structure](/arcmenu-wiki/menu-configuration/menus.md) for the top-level configuration.

## Canvas settings: `canvas`

`canvas` is a top-level menu section supported on Paper, Folia, Leaf and Spigot.

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

### `width` and `height`

Set the logical canvas width and height. The example uses `320 × 180`, with a `16:9` aspect ratio.

These values define the canvas dimensions, not the player's monitor resolution. Changing them does not automatically rearrange elements or update button hit regions.

The canvas center is `(0, 0)`. For the example above, the reference edges are:

| Position | Coordinate |
| -------- | ---------- |
| Left     | `x: -160`  |
| Right    | `x: 160`   |
| Top      | `y: 90`    |
| Bottom   | `y: -90`   |

Allow room for the dimensions of text and buttons, rather than placing only their centers within these edges.

### `pixels-per-block`

Sets the relationship between canvas units and in-game size. With other settings unchanged:

* Higher values make the menu and its elements appear smaller.
* Lower values make them appear larger.

This affects both visible content and hit regions. Use it to change the overall menu size without editing each element's coordinates.

### `distance`

Sets the menu's design distance in blocks. With other settings unchanged, increasing it makes the menu appear smaller in the player's view; decreasing it makes the menu appear larger.

Its use differs by server type:

| Server                                    | Effect of `canvas.distance`                                                                    |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Paper, Folia, Leaf and compatible servers | Establishes the menu's apparent scale; physical screen distance is configured in `offset.yml`. |
| Spigot                                    | Sets the distance between the menu and the player's viewpoint.                                 |

`width`, `height`, `pixels-per-block` and `distance` must all be greater than `0`. Their defaults are `320`, `180`, `100` and `3`, respectively.

## Menu layout coordinates

### Directions and units

| Axis | Positive direction | Negative direction   |
| ---- | ------------------ | -------------------- |
| `x`  | Right              | Left                 |
| `y`  | Up                 | Down                 |
| `z`  | Toward the player  | Away from the player |

Menu positions and dimensions use canvas units, not block distances. For example, a button with `width: 60` is `60` canvas units wide.

### Visible element positions

Set an element's position in its `offset` section under `frontend`. Use `x` and `y` for layout and `z` for layering.

Give text a larger `z` than its button background to place it in front and prevent the background from covering it. Omitted offset axes default to `0`.

Elements inside a group are positioned relative to that group. This page uses top-level elements; see [Groups and reusable templates](/arcmenu-wiki/menu-configuration/menus/groups-templates.md) for group positioning and scaling.

### Hit-region positions

Set a region's center using `x` and `y` under its `backend` entry. `width` and `height` define its dimensions.

Hit regions have no `offset` or `z` fields. Configure them separately from the visible button.

The following button sits below the canvas center, with matching background, text and hit region. This fragment replaces or adds the corresponding menu sections; it is not a complete menu file.

```yaml
frontend:
  close-button:
    type: rectangle
    width: 60
    height: 18
    color: '#365E91'
    offset: {x: 0, y: -20, z: 1}
  close-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
```

To move the button right, update `offset.x` on the background and text, and `x` on the region. When resizing the button, adjust the region dimensions too.

Moving, rotating or scaling a frontend group does not automatically change its hit regions. Full element properties are covered in [Frontend element types](/arcmenu-wiki/menu-configuration/menus/frontend.md).

## Screen placement: `offset.yml`

This section applies only to Paper, Folia, Leaf and compatible servers. The file is `plugins/ArcMenu/offset.yml`. Settings affect all menus opened in the corresponding interaction mode; mouse settings also affect menus in the editor.

Spigot does not use this file. Set distance with the menu's `canvas.distance` instead.

### Interaction modes

`touch` configures touch mode and `mouse` configures mouse mode. Each can be adjusted independently. The default configuration is:

```yaml
touch:
  distance: 0.65
  offset:
    x: 0.0
    y: 0.0
    z: 0.0

mouse:
  distance: 0.65
  offset:
    x: 0.0
    y: 0.0
    z: 0.0
```

### `distance`

Sets the distance between the screen and the player's viewpoint in blocks. The allowed range is `0.1` to `16`.

ArcMenu preserves the menu's apparent size when changing this distance. To enlarge or shrink the menu, change its `pixels-per-block` or design distance instead of adjusting only this setting.

### `offset`

Moves the entire screen relative to its original position, in blocks. Directions follow the menu screen, not world coordinates.

* Positive `x` moves right; negative moves left.
* Positive `y` moves up; negative moves down.
* Positive `z` moves toward the player; negative moves away.

Each axis accepts values from `-16` to `16` and defaults to `0`. Moving the entire screen moves both visible content and hit regions without editing individual elements.

For example, slightly raise menus in touch mode by changing `touch.offset.y` from `0.0` to `0.05`. Start with small adjustments and reopen the menu to check the result.

## Applying and checking changes

| Goal                              | Setting to change                                                         |
| --------------------------------- | ------------------------------------------------------------------------- |
| Move one button                   | The button elements' `offset` and the corresponding region's `x` and `y`. |
| Resize a button's hit region      | The region's `width` and `height`; check the visible button size as well. |
| Enlarge or shrink the entire menu | The menu's `canvas.pixels-per-block` or `canvas.distance`.                |
| Reposition all menus              | `offset.yml` on Paper-based servers.                                      |
| Change physical screen distance   | `offset.yml` on Paper-based servers; `canvas.distance` on Spigot.         |

Save, run `/arcmenu reload` and reopen the menu. Check that visible buttons and hit regions align. In mouse mode, also check cursor movement and buttons near the edges. Relevant commands are listed in [Commands and permissions](/arcmenu-wiki/configuration-and-administration/commands-permissions.md).