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

# clickable areas

Clickable areas define interactive zones in cursor coordinate space.\
Each area is identified by a unique key under `clickable_areas` and is evaluated against cursor `X/Y`.

## Where to configure

Main merge target:

* `clickable_areas` in runtime config

Recommended source files:

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

You can split areas across multiple YAML files.

## Fast area selection with `/cursor area`

Use this to get exact coordinates without guessing:

{% stepper %}
{% step %}

#### Start cursor mode

```bash
/cursor start
```

{% endstep %}

{% step %}

#### Enable debug mode (recommended while authoring)

```bash
/cursor debug
```

{% endstep %}

{% step %}

#### Enable area selection

```bash
/cursor area
```

{% endstep %}

{% step %}

#### Click point 1 with the cursor

{% endstep %}

{% step %}

#### Click point 2 with the cursor

After point 2, chat feedback includes:

* Point 1 and Point 2
* Calculated `min_x`, `max_x`, `min_y`, `max_y`
* Width and height

Copy these values directly into YAML.
{% endstep %}
{% endstepper %}

## Base schema

```yaml
my_area_name:
  min_x: <number>
  max_x: <number>
  min_y: <number>
  max_y: <number>
  action: "change_hologram|apply_group|apply_holograms|command"
  target: "<string>"                  # optional (legacy/fallback)
  hologram_to_change: "<string>"      # optional (action dependent)
  change_to: "<string>"               # optional (action dependent)
  new_text: "<string>"                # optional
  message: "<string>"                 # optional
  command: "<string>"                 # optional
  priority: 0                           # optional, default 0
  conditions:                           # optional
    required_group: "<string>"
  on_hover:                             # optional, list
    - type: "scale"
      hologram: "<string>"
      scale: 0.15
      duration: 0.2
      interpolation: "ease_in_out"
  on_unhover:                           # optional, list
    - type: "scale"
      hologram: "<string>"
      scale: 0.13
      duration: 0.5
      interpolation: "ease_out"
```

## Field reference

| Field                | Type    |         Required | Default           | Notes                                             |
| -------------------- | ------- | ---------------: | ----------------- | ------------------------------------------------- |
| `min_x`              | number  |              Yes | `0.0`             | Inclusive lower bound                             |
| `max_x`              | number  |              Yes | `0.0`             | Inclusive upper bound                             |
| `min_y`              | number  |              Yes | `0.0`             | Inclusive lower bound                             |
| `max_y`              | number  |              Yes | `0.0`             | Inclusive upper bound                             |
| `action`             | string  |               No | `change_hologram` | Supported values listed below                     |
| `priority`           | integer |               No | `0`               | Higher value wins on overlap                      |
| `conditions`         | map     |               No | none              | Conditional activation rules                      |
| `on_hover`           | list    |               No | none              | Runs when cursor enters area                      |
| `on_unhover`         | list    |               No | none              | Runs when cursor exits area                       |
| `command`            | string  | Action-dependent | none              | Used by `action: command`                         |
| `hologram_to_change` | string  | Action-dependent | none              | Used by `change_hologram`                         |
| `change_to`          | string  | Action-dependent | none              | Used by group/hologram actions                    |
| `new_text`           | string  |               No | none              | Used by `change_hologram`                         |
| `message`            | string  |               No | none              | Used by `change_hologram` fallback                |
| `target`             | string  |               No | none              | Legacy fallback for `hologram_to_change` or group |

### Compatibility aliases

The loader also supports these aliases:

* `target_hologram` -> `hologram_to_change`
* `new_hologram` -> `change_to`

## Conditions (supported keys)

| Condition key    | Value type            | Behavior                                                                                     |
| ---------------- | --------------------- | -------------------------------------------------------------------------------------------- |
| `required_group` | string                | Requires active group to match. Special case: `default` accepts `null/default` startup state |
| `required_class` | string                | Requires active class exact match                                                            |
| `group_exists`   | string                | Area is valid only if that group exists in config                                            |
| `has_class`      | `"true"` or `"false"` | Checks whether a class is currently selected                                                 |
| `class_contains` | string                | Active class must contain this text (case-insensitive)                                       |

Unknown condition keys are treated as invalid (area fails).

## Click actions

### `change_hologram`

Changes text of an existing static hologram.

#### Key behavior

* Target hologram resolution:
  * `hologram_to_change`
  * fallback: `target`
* New text resolution priority:
  1. `new_text`
  2. `change_to` as source hologram name (copies source text if found)
  3. `message`
  4. internal fallback text

#### Example: direct text

```yaml
open_shop:
  min_x: 1.10
  max_x: 1.40
  min_y: 0.20
  max_y: 0.35
  action: "change_hologram"
  hologram_to_change: "center"
  new_text: "§aShop opened\n§7Choose an option"
```

#### Example: copy text from another hologram

```yaml
copy_from_info:
  min_x: 1.45
  max_x: 1.70
  min_y: 0.20
  max_y: 0.35
  action: "change_hologram"
  hologram_to_change: "center"
  change_to: "info"
```

### `apply_group`

Applies a **class group** (non-activable group).

#### Required

* `change_to` or `target` with group name

#### Example

```yaml
set_assassin:
  min_x: -1.0
  max_x: -0.7
  min_y: 0.1
  max_y: 0.3
  action: "apply_group"
  change_to: "assassin_class"
```

### `apply_holograms`

Applies an **activable hologram group**.

#### Required

* `change_to` or `target` with activable group name

#### Example

```yaml
go_to_gacha:
  min_x: 2.34
  max_x: 2.48
  min_y: 0.38
  max_y: 0.44
  action: "apply_holograms"
  change_to: "gacha"
  conditions:
    required_group: "wish"
```

### `command`

Executes a player command with `performCommand(...)`.

#### Required

* `command`

#### Example

```yaml
start_flow:
  min_x: 0.10
  max_x: 0.40
  min_y: 0.15
  max_y: 0.28
  action: "command"
  command: "cursor start"
```

Recommended: define the command **without** a leading `/`.

## Hover actions (`on_hover` / `on_unhover`)

`on_hover` and `on_unhover` accept a list of action objects.\
Each object must include at least `type`.

### Supported hover action types

* `scale`
* `move`
* `rotate`
* `combined`
* `change_text`

### Hover object fields

| Field                                 | Type             | Used by                          |
| ------------------------------------- | ---------------- | -------------------------------- |
| `type`                                | string           | all                              |
| `hologram`                            | string           | all supported types              |
| `scale`                               | number           | `scale`, `combined`              |
| `offset_x` or `offsetX`               | number           | `move`, `combined`               |
| `offset_y` or `offsetY`               | number           | `move`, `combined`               |
| `offset_z` or `offsetZ`               | number           | `move`, `combined`               |
| `posX`, `posY`, `posZ`                | number           | `move`, `combined` absolute mode |
| `rotationX`, `rotationY`, `rotationZ` | number           | `rotate`, `combined`             |
| `duration`                            | number (seconds) | all animation types              |
| `interpolation`                       | string           | all animation types              |
| `newText`                             | string           | `change_text` on hover           |
| `text`                                | string           | `change_text` on unhover         |

### Interpolation values

* `linear`
* `ease_in`
* `ease_out`
* `ease_in_out`

If `duration <= 0`, the change is applied instantly.

### Example: scale on hover/unhover

```yaml
exit_button:
  min_x: 2.34
  max_x: 2.48
  min_y: 0.38
  max_y: 0.44
  action: "command"
  command: "cursor start"
  on_hover:
    - type: "scale"
      hologram: "exit_button"
      scale: 0.15
      duration: 0.2
      interpolation: "ease_in_out"
  on_unhover:
    - type: "scale"
      hologram: "exit_button"
      scale: 0.13
      duration: 0.5
      interpolation: "ease_out"
```

### Example: move with offsets

```yaml
hover_shift:
  min_x: -0.4
  max_x: -0.1
  min_y: 0.2
  max_y: 0.4
  action: "command"
  command: "say hovered"
  on_hover:
    - type: "move"
      hologram: "left"
      offset_x: 0.10
      offset_y: 0.05
      duration: 0.15
      interpolation: "ease_out"
  on_unhover:
    - type: "move"
      hologram: "left"
      offset_x: 0.00
      offset_y: 0.00
      duration: 0.25
      interpolation: "ease_in_out"
```

### Example: combined transform

```yaml
combo_anim:
  min_x: -1.2
  max_x: -0.9
  min_y: 0.1
  max_y: 0.3
  action: "command"
  command: "say combo"
  on_hover:
    - type: "combined"
      hologram: "center"
      scale: 0.16
      offset_x: 0.08
      offset_y: 0.04
      rotationY: 0.30
      duration: 0.2
      interpolation: "ease_in_out"
```

### Example: hover text swap

```yaml
hover_text:
  min_x: 0.2
  max_x: 0.5
  min_y: 0.2
  max_y: 0.4
  action: "command"
  command: "say text"
  on_hover:
    - type: "change_text"
      hologram: "center"
      newText: "§aReady"
  on_unhover:
    - type: "change_text"
      hologram: "center"
      text: "§7Idle"
```

## Overlap and priority

If multiple areas overlap at the same cursor position:

* Conditions are evaluated first.
* Highest `priority` wins.
* Default priority is `0`.

Use explicit priorities for deterministic behavior.

## Troubleshooting checklist

* Verify area bounds from `/cursor area` output.
* Verify current group/class if using `conditions`.
* Verify the target hologram name exists in the active session/group.
* Use `/cursor debug` while testing.
* For command actions, verify command syntax and permissions.


---

# 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/clickable-areas.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.