> For the complete documentation index, see [llms.txt](https://xcs-plugin.gitbook.io/cursorcs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://xcs-plugin.gitbook.io/cursorcs/guides/building-clickable-menus.md).

# building clickable menus

This guide explains the easiest way to create clickable menu areas in CursorCs.

If you want the full field-by-field reference, see [Clickable Areas](/cursorcs/guides/clickable-areas.md).

## What a clickable area is

A clickable area is a rectangle in cursor space.\
When the player's cursor enters that rectangle, you can react with hover actions.\
When the player clicks inside it, you can run one or more actions.

Typical uses:

* buttons
* tabs
* language selectors
* menu switches
* external links

## Where to put clickable areas

Recommended location:

```
plugins/CursorCs/config/clickable/
```

Example:

```
plugins/CursorCs/config/clickable/buttons.yml
```

After editing clickable areas, reload them with:

```bash
/cursor reloadclickable
```

## The simplest button

This button runs a command when clicked:

```yaml
play_button:
  min_x: -0.30
  max_x: 0.30
  min_y: -0.10
  max_y: 0.15
  action: "command"
  command: "say button clicked"
```

## How to get the coordinates

{% stepper %}
{% step %}
Start cursor mode:

```bash
/cursor start
```

{% endstep %}

{% step %}
Enable debug mode:

```bash
/cursor debug
```

{% endstep %}

{% step %}
Enable area selection:

```bash
/cursor area
```

{% endstep %}

{% step %}
Click point 1.
{% endstep %}

{% step %}
Click point 2.
{% endstep %}

{% step %}
Copy the generated `min_x`, `max_x`, `min_y`, `max_y`.
{% endstep %}
{% endstepper %}

## Hover effect example

You can animate a hologram when the cursor enters or leaves the area:

```yaml
play_button:
  min_x: -0.30
  max_x: 0.30
  min_y: -0.10
  max_y: 0.15
  on_hover:
    - type: "scale"
      hologram: "play_button"
      scale: 0.18
      duration: 0.15
      interpolation: "ease_out"
  on_unhover:
    - type: "scale"
      hologram: "play_button"
      scale: 0.15
      duration: 0.15
      interpolation: "ease_out"
```

## Click animation example

You can chain multiple actions in `on_click`:

```yaml
language_button:
  min_x: -0.30
  max_x: 0.30
  min_y: -0.10
  max_y: 0.15
  on_click:
    - type: "move"
      hologram: "lenguaje2"
      mode: "absolute"
      offset_y: 0.5
      duration: 0.25
      interpolation: "ease_out"
    - type: "start_text_animation"
      hologram: "english_text"
```

`on_click` is the most flexible way to build interactive menus.

## Open a menu with a button

To switch to another menu state without rebuilding the whole screen:

```yaml
to_english:
  min_x: -0.30
  max_x: 0.30
  min_y: -0.10
  max_y: 0.15
  on_click:
    - type: "apply_group"
      change_to: "en"
```

To switch to a full activable menu:

```yaml
to_shop:
  min_x: -0.30
  max_x: 0.30
  min_y: -0.10
  max_y: 0.15
  on_click:
    - type: "apply_holograms"
      change_to: "shop_menu"
```

If you are not sure which one to use, see [Groups and Menu Switching](broken://pages/434a19eed7687573340a4011aa40fdbe646064ec).

## Restrict an area to one menu state

You can make areas work only in a specific active group:

```yaml
default_only_button:
  min_x: 0.10
  max_x: 0.30
  min_y: 0.10
  max_y: 0.20
  conditions:
    required_group: "default"
  on_click:
    - type: "apply_group"
      change_to: "en"
```

And another one that only works after the switch:

```yaml
en_only_button:
  min_x: 0.10
  max_x: 0.30
  min_y: 0.10
  max_y: 0.20
  conditions:
    required_group: "en"
  on_click:
    - type: "command"
      command: "say en-active"
```

## Open an external link

Clickable areas can send a clickable link to the player:

```yaml
website_button:
  min_x: 0.80
  max_x: 1.20
  min_y: 0.10
  max_y: 0.25
  on_click:
    - type: "open_url"
      url: "https://example.com/store"
      link_text: "§b§nOpen store"
      hover_text: "§7Open store in browser"
```

This uses Minecraft's normal link-confirmation flow.

## Useful actions to know

Common action types:

* `command`
* `apply_group`
* `apply_holograms`
* `clear_group`
* `change_text`
* `change_cursor`
* `sound`
* `open_url`
* `move`
* `scale`
* `rotate`
* `combined`
* `preset_animation`
* `start_animation`
* `start_text_animation`
* `start_spawn_animation`

## Recommended workflow

1. Build the holograms first.
2. Add one clickable area per button.
3. Test the coordinates with `/cursor area`.
4. Add hover effects.
5. Add click actions.
6. Add `required_group` once the menu states are working.


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://xcs-plugin.gitbook.io/cursorcs/guides/building-clickable-menus.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.