> 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/reference/config-system-and-holograms.md).

# config system and holograms

This guide explains how CursorCs reads configuration, how each config folder works, and how to create holograms correctly.

## Configuration loading model

CursorCs loads from `config.yml` and then merges folder-based files into runtime paths:

1. `config/clickable/*.yml` -> merged into `clickable_areas.*`
2. `config/holograms/*.yml` (files **without** root `group:`) -> merged into `camera_holograms.static_holograms.*`
3. `config/groups/*.yml` -> merged into `hologram_groups.*`

Important behavior:

* If two files use the same top-level key, later-loaded values overwrite earlier ones.
* Files in `config/holograms/` that contain root `group:` are treated as **activable groups**, not static merge files.

## `config.yml` (base settings)

Main sections you should maintain:

* `cursor.sensitivity.x`
* `cursor.sensitivity.y`
* `cursor.maxOffset.x`
* `cursor.maxOffset.y`
* `cursor.distance`
* `cursor.prediction.enabled`
* `cursor.prediction.strength`
* `cursor.prediction.history_frames`
* `cursor.prediction.min_ping_threshold`
* `cursor.prediction.smoothing_factor`
* `cursor.prediction.debug`
* `hologram.distance`
* `hologram.separation`
* `hologram.rotationAngle`
* `camera.distance`

Minimal example:

```yaml
cursor:
  sensitivity:
    x: 0.02
    y: 0.01
  maxOffset:
    x: 5.0
    y: 0.88
  distance: 2.0
  prediction:
    enabled: false
    strength: 0.3
    history_frames: 5
    min_ping_threshold: 100
    smoothing_factor: 0.7
    debug: false

hologram:
  distance: 3.0
  separation: 2.0
  rotationAngle: 25.0

camera:
  distance: 200.0
```

## `config/` folder architecture

Recommended production layout:

```
plugins/CursorCs/
  config.yml
  config/
    clickable/
      buttons.yml
      shop.yml
    holograms/
      static_holograms.yml
      hud.yml
      gacha.yml          # can be static or activable group file
    groups/
      classes.yml
      roles.yml
```

Use separate files per feature/state to keep maintenance clean.

## `config/holograms/` (static holograms)

A static hologram entry is a top-level key with visual properties.

Example:

```yaml
banner:
  text: "§f§lWELCOME"
  offset_x: 0.0
  offset_y: 1.2
  offset_z: 0.0
  scale: 0.9
  rotation_x: 0.0
  rotation_y: 0.0
  rotation_z: 0.0
  alignment: "CENTER"
  line_width: 200
  opacity: 255
  billboard: "CENTER"
  see_through: false
  shadow: true
  background_r: 0
  background_g: 0
  background_b: 0
  background_a: 0
```

### Hologram fields reference

| Field              | Type   | Required | Default  | Notes                                       |
| ------------------ | ------ | -------: | -------- | ------------------------------------------- |
| `text`             | string |    Yes\* | `""`     | If empty, static creation is skipped        |
| `offset_x`         | number |       No | `0.0`    | Relative to camera                          |
| `offset_y`         | number |       No | `0.0`    |                                             |
| `offset_z`         | number |       No | `-2.0`   |                                             |
| `scale`            | number |       No | `0.8`    |                                             |
| `rotation_x`       | number |       No | `0.0`    | Degrees                                     |
| `rotation_y`       | number |       No | `0.0`    | Degrees                                     |
| `rotation_z`       | number |       No | `0.0`    | Degrees                                     |
| `alignment`        | string |       No | `CENTER` | `CENTER`, `LEFT`, `RIGHT`                   |
| `line_width`       | int    |       No | `200`    |                                             |
| `opacity`          | int    |       No | `255`    | `0-255`                                     |
| `billboard`        | string |       No | `CENTER` | `CENTER`, `HORIZONTAL`, `VERTICAL`, `FIXED` |
| `see_through`      | bool   |       No | `false`  |                                             |
| `shadow`           | bool   |       No | `false`  |                                             |
| `background_r/g/b` | int    |       No | `0`      | `0-255`                                     |
| `background_a`     | int    |       No | `255`    |                                             |

`*` A hologram can also be created from animation-first-frame text in advanced animation setups.

## Special hologram content types (`item:`, `block:`, `entity:`)

CursorCs parses `text` prefixes to render non-text holograms.

### 1) Item hologram

```yaml
weapon_icon:
  text: "item:minecraft:diamond_sword"
  offset_x: 1.2
  offset_y: 0.4
  offset_z: 0.0
  scale: 0.8
```

### 2) Block hologram

```yaml
stone_icon:
  text: "block:minecraft:stone"
  offset_x: -1.2
  offset_y: 0.4
  offset_z: 0.0
  scale: 0.8
```

### 3) Entity hologram

```yaml
pet_preview:
  text: "entity:minecraft:wolf"
  offset_x: 0.0
  offset_y: 0.1
  offset_z: 0.0
  scale: 0.8
```

Notes:

* `entity:minecraft:player` is rejected.
* If `item/block/entity` is invalid, CursorCs falls back to regular text hologram behavior.
* Hover animation actions in clickable areas target `TextDisplay` names, so design your interaction targets accordingly.

## `config/groups/` (class groups)

Group files are merged under `hologram_groups` and used by `apply_group`.

You can define:

* simple text values
* nested groups (`skills.skill_1`, etc.)
* map-based per-hologram overrides

Example:

```yaml
warrior_class:
  right: "§c§lWARRIOR"
  left: "§7Stats"
  center: "§7Skills"
  skills:
    skill_1: "§cSlash"
    skill_2: "§cShield"
```

Advanced map override inside groups:

```yaml
warrior_class:
  center:
    text: "§c§lWARRIOR HUD"
    scale: 0.95
    offset_x: 0.0
    offset_y: -0.6
    line_width: 260
    disable_hover: true
```

### Group-specific extra value

* `restore_holograms`: restore one or multiple holograms to their original config

Examples:

```yaml
warrior_class:
  restore_holograms: "left,right"
```

or

```yaml
warrior_class:
  restore_holograms:
    - left
    - right
```

## Activable groups inside `config/holograms/`

If a hologram YAML has root `group: <name>`, it is loaded as an activable group and used by `apply_holograms`.

Example file: `config/holograms/gacha.yml`

```yaml
group: "gacha"

banner:
  text: "§6§lGACHA"
  offset_x: 0.0
  offset_y: 1.0
  offset_z: 0.0
  scale: 1.0

exit:
  text: "§fBack"
  offset_x: 2.4
  offset_y: 0.4
  offset_z: 0.0
  scale: 0.13
```

Use from clickable area:

```yaml
open_gacha:
  min_x: 2.34
  max_x: 2.48
  min_y: 0.38
  max_y: 0.44
  action: "apply_holograms"
  change_to: "gacha"
```

## Which file should I use?

* Use `config.yml` for global behavior (cursor/camera/sensitivity/prediction).
* Use `config/holograms/` for visual elements and UI states.
* Use `config/groups/` for class-oriented group logic and nested skill trees.
* Use `config/clickable/` for interactions and hover behavior.

## Reload workflow

After edits:

* `/cursor reload` (full reload)
* `/cursor reloadholograms`
* `/cursor reloadgroups`
* `/cursor reloadclickable`

For layout tuning, combine with:

```bash
/cursor debug
/cursor area
```


---

# 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/reference/config-system-and-holograms.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.