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

# holograms Options

This document lists the hologram configuration keys that are currently implemented in CursorCs.

It applies to:

* `config/holograms/*.yml`
* activable hologram files that use a top-level `group: ...`
* `config/groups/*.yml` for class/group overrides

## Base Keys

### `text`

String.

Special prefixes:

* `item:<material>`
* `item:<material>:<custom_model_data>`
* `item:ia:<namespace:id>`
* `item:itemsadder:<namespace:id>`
* `item:nexo:<item_id>`
* `block:<material>`
* `block:ia:<namespace:id>`
* `block:nexo:<block_id>`
* `entity:<entity_type>`
* `entity:ia:<namespace:id>`
* `entity:nexo:<furniture_or_entity_id>`
* `entity:fancynpc:npc`

Also accepted for FancyNPC:

* `entity:fancy_npc:npc`
* `entity:fancynpcs:npc`

If a visual value cannot be resolved, CursorCs falls back to a text hologram.

### `offset_x`, `offset_y`, `offset_z`

Double. Offset relative to the camera hologram position.

### `scale`

Double. Uniform scale.

### `rotation_x`, `rotation_y`, `rotation_z`

Double. Rotation in degrees.

### `visible`

Boolean. Controls whether the hologram or entity is shown to the player.

## TextDisplay Keys

These keys apply to normal text holograms. `billboard`, `scale`, `rotation_*`, and `brightness_*` are also used by item and block displays.

### `alignment`

String. `CENTER`, `LEFT`, or `RIGHT`. (only works with width)

### `line_width`

Integer. Maximum line width in pixels.

### `opacity`

Integer from `0` to `255`. Text opacity.

### `billboard`

String. `CENTER`, `HORIZONTAL`, `VERTICAL`, or `FIXED`.

### `see_through`

Boolean.

### `shadow`

Boolean.

### `background_r`, `background_g`, `background_b`, `background_a`

Integer from `0` to `255`. Background color and alpha.

### `brightness_block`, `brightness_sky`

Integer from `0` to `15`. Forced display light.

## Realtime Placeholders and States

### `placeholder_refresh_interval_ticks`

Integer.

* `0` disables refresh.
* If `states` is present and no explicit refresh interval is set, CursorCs refreshes every `20` ticks.

### `states`

Map of named states. Each state can override any normal hologram key.

Supported state metadata:

* `filters`
* `priority`
* `apply_group`
* `apply_holograms`
* `clear_group`

### `filters`

Only valid inside a state.

Supported filter keys:

* `permission`
* `world`
* `gamemode`
* `placeholder`
* `operator`
* `value`
* `mode`
* `conditions`
* `preset`

Supported placeholder operators:

* `==`, `!=`, `>`, `>=`, `<`, `<=`
* `contains`
* `starts_with`
* `ends_with`

### `filter_presets`

Top-level map that can be shared across hologram and group files.

## Text Animation

### `animation`

Supported forms:

* multiline string
* YAML list
* map with `frames`

### Animation mode keys

* top-level `type`
* top-level `animation_type`
* inside `animation`: `type` or `mode`

Supported values:

* `loop`
* `one`, `one_time`, `one-time`

### Animation timing keys

* top-level `animation_interval_ticks`
* top-level `animation_enabled`
* inside `animation`: `interval_ticks`, `enabled`

### Text animation end actions

Supported keys:

* `animation_on_end`
* `text_animation_on_end`
* `on_animation_end`
* inside `animation`: `on_end`, `end_actions`, `actions_on_end`

Each action can be:

* a string command
* a map with:
  * `type`: `command`, `remove_hologram`, `start_animation`
  * `command` or `commands`
  * `executor`
  * `as_op`
  * `hologram` or `target`
  * `animation` or `mode`

## Spawn Animation

### `animations`

Defines spawn, movement, and scale animation steps.

Each step supports:

* `type`: `play_once`, `loop`, `loop_pingpong`
* `duration`
* `from_x`, `to_x`
* `from_y`, `to_y`
* `from_z`, `to_z`
* `from_scale`, `to_scale`

The `animations` section can be:

* a single step map
* a numbered map of steps
* a list of steps

### Spawn animation trigger keys

Top level:

* `spawn_animation_trigger`
* `animation_trigger`
* `spawn_animation_delay_seconds`
* `animation_delay_seconds`
* `spawn_delay_seconds`

Inside `animations`:

* `trigger`
* `start`
* `start_when`
* `delay_seconds`
* `delay`
* `animation_to_end`
* `trigger_animation_to_end`

Supported trigger values:

* `immediate`
* `after_seconds`
* `after_text_animation_end`

### Spawn animation end actions

Supported keys:

* `spawn_animation_on_end`
* `animations_on_end`
* inside `animations`: `on_end`, `end_actions`, `actions_on_end`

They use the same action format as text animation end actions.

## Group-only Keys

These keys are not base static hologram keys. They are read when applying class/group overrides from `hologram_groups`.

### `disable_hover`

Boolean.

This is only handled by the class/group override path. It is not part of the base static hologram loader.

### `restore_holograms`

Special entry inside a `hologram_groups` group.

Accepted forms:

* comma-separated string
* YAML list

When applied, CursorCs restores the original saved configuration for the listed holograms.

## FancyNPC Entity Holograms

Use `text: "entity:fancynpc:npc"` and add a `fancynpc` section.

Supported `fancynpc` keys:

* `skin`
* `display_name`
* `show_display_name`
* `scale`
* `show_in_tab`
* `spawn_entity`
* `collidable`
* `glowing`
* `glowing_color`
* `turn_to_player`
* `turn_to_player_distance`
* `interaction_cooldown`
* `visibility_distance`
* `mirror_skin`
* `rotation_body_y`
* `rotation_head_y`
* `rotation_head_x`
* `equipment`

Supported `equipment` slots:

* `main_hand`
* `off_hand`
* `helmet`
* `chestplate`
* `leggings`
* `boots`

Notes:

* Top-level `glowing` is not a normal hologram key. It only exists inside `fancynpc`.
* For living or custom entity holograms, `rotation_x` and `rotation_y` map to pitch and yaw. `rotation_z` has no direct effect.
* Text-only options such as `alignment`, `line_width`, `opacity`, `see_through`, `shadow`, and background color do not affect non-text entity holograms.

## Minimal Examples

### Basic text hologram

```yaml
title:
  text: "Welcome"
  offset_x: 0.0
  offset_y: 1.0
  offset_z: -2.0
  scale: 0.8
  rotation_x: 0.0
  rotation_y: 0.0
  rotation_z: 0.0
  visible: true
  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
  brightness_block: 15
  brightness_sky: 15
```

### Visual item hologram

```yaml
sword_icon:
  text: "item:minecraft:diamond_sword:2550"
  offset_x: 0.0
  offset_y: 0.5
  offset_z: -1.8
  scale: 1.0
  rotation_y: 20.0
  billboard: "CENTER"
  brightness_block: 15
  brightness_sky: 15
```

### Conditional state hologram

```yaml
filter_presets:
  vip_spawn:
    mode: "AND"
    conditions:
      - permission: "vip"
      - world: "spawn"

status:
  text: "Lobby"
  placeholder_refresh_interval_ticks: 20
  states:
    vip:
      priority: 100
      filters:
        preset: "vip_spawn"
      text: "VIP Area"
    default:
      text: "Lobby"
```

### Text animation

```yaml
loading:
  animation:
    frames:
      - "Loading."
      - "Loading.."
      - "Loading..."
    mode: "loop"
    interval_ticks: 4
```

### Group override

```yaml
hologram_groups:
  selected_class:
    title:
      text: "Archer"
      scale: 1.1
      offset_y: 0.4
      opacity: 220
      disable_hover: true
    restore_holograms:
      - info
      - preview
```

### FancyNPC hologram

```yaml
npc_selector:
  text: "entity:fancynpc:npc"
  offset_x: 0.0
  offset_y: 0.2
  offset_z: -1.5
  scale: 1.0
  rotation_y: 0.0
  visible: true
  fancynpc:
    skin: "Notch"
    display_name: "Class Selector"
    show_display_name: true
    scale: 1.8
    show_in_tab: false
    collidable: false
    glowing: false
    rotation_body_y: 0.0
    rotation_head_y: 0.0
    rotation_head_x: 0.0
    equipment:
      main_hand: "minecraft:diamond_sword:2550"
      helmet: "minecraft:diamond_helmet"
```

## Important Notes

* `disable_hover` and `restore_holograms` are group features, not regular static hologram keys.
* `glowing` was removed from the old top-level examples because it is not implemented as a normal text hologram option.
* `background_a` is supported and controls background alpha.
* `filters` without `states` is treated as invalid.
* Visual item, block, and entity holograms can still use placeholder and state resolution because the resolved `text` field is parsed before the content type is created.


---

# 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/holograms-options.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.