> 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/hologram-animations.md).

# hologram animations

This file documents the hologram animation systems currently supported by CursorCS.

There are 2 main animation types:

* `animation`: text/frame animation
* `animations`: spawn/transform animation

***

## 1. Text Animation

Text animation changes the hologram text over time using frames.

### Basic Example

```yaml
my_hologram:
  text: "" # optional; if empty, the first animation frame is shown
  animation:
    enabled: true # enables/disables text animation
    type: "loop" # supported: loop, one, one_time, one-time
    interval_ticks: 5 # ticks between frames, minimum 1
    frames:
      - "Frame 1"
      - "Frame 2"
      - "Frame 3"
```

### Supported Options

```yaml
my_hologram:
  animation: # required for text animation
    enabled: true # true/false, default true
    type: "loop" # loop | one | one_time | one-time
    mode: "loop" # alias of type
    interval_ticks: 5 # delay between frames in ticks, minimum 1
    frames: # list of animation frames
      - "Text 1"
      - "Text 2"
      - "Text 3"
```

### Legacy / Alternative Supported Keys

These keys are also supported outside the `animation` block:

```yaml
my_hologram:
  animation:
    - "Frame 1"
    - "Frame 2"
    - "Frame 3"

  type: "loop" # alias
  animation_type: "loop" # alias
  animation_interval_ticks: 5 # alias
  animation_enabled: true # alias
```

### Multi-line Frame Input

You can also provide frames as a multi-line string:

```yaml
my_hologram:
  animation: |
    Frame 1
    Frame 2
    Frame 3
```

### Supported Text Animation Modes

```yaml
type: "loop" # repeats forever
type: "one" # plays once
type: "one_time" # plays once
```

***

## 2. Spawn / Transform Animation

Spawn animation animates position and/or scale when the hologram appears.

### Basic Example

```yaml
my_hologram:
  text: "Hello"
  animations:
    trigger: "immediate" # when the animation starts
    delay_seconds: 0.0 # optional delay
    animation_to_end: "other_hologram" # used for after_text_animation_end triggers

    1:
      type: "play_once" # play_once | once | one | one_time | one-time | loop | repeat | loop_pingpong | ping_pong | ping-pong | yoyo | loop_yoyo
      duration: 20 # duration in ticks, minimum 1
      from_x: -0.5 # starting X
      to_x: 0.0 # ending X
      from_y: -0.5 # starting Y
      to_y: 0.0 # ending Y
      from_z: 0.0 # starting Z
      to_z: 0.0 # ending Z
      from_scale: 0.0 # starting scale
      to_scale: 1.0 # ending scale
```

### Supported Options

```yaml
my_hologram:
  animations:
    trigger: "immediate" # aliases: trigger, start, start_when
    delay_seconds: 0.0 # aliases: delay_seconds, delay
    animation_to_end: "other_hologram" # used when waiting for another text animation to finish

    1:
      type: "play_once" # play_once | once | one | one_time | one-time | loop | repeat | loop_pingpong | ping_pong | ping-pong | yoyo | loop_yoyo
      duration: 20 # duration in ticks, minimum 1
      from_x: 0.0 # alias: fromX
      to_x: 0.0 # alias: toX
      from_y: 0.0 # alias: fromY
      to_y: 0.0 # alias: toY
      from_z: 0.0 # alias: fromZ
      to_z: 0.0 # alias: toZ
      from_scale: 1.0 # alias: fromScale
      to_scale: 1.0 # alias: toScale
```

### Single-Step Format

You can also define a single animation step without numbering:

```yaml
my_hologram:
  text: "Hello"
  animations:
    type: "play_once"
    duration: 20
    from_y: -0.5
    to_y: 0.0
    from_scale: 0.0
    to_scale: 1.0
```

### List Format

You can also define animation steps as a YAML list:

```yaml
my_hologram:
  text: "Hello"
  animations:
    - type: "play_once"
      duration: 20
      from_y: -0.5
      to_y: 0.0
      from_scale: 0.0
      to_scale: 1.0
    - type: "loop_pingpong"
      duration: 30
      from_y: 0.0
      to_y: 0.1
```

### Supported Spawn Animation Modes

```yaml
type: "play_once" # plays once
type: "once" # alias of play_once
type: "one" # alias of play_once
type: "one_time" # alias of play_once
type: "one-time" # alias of play_once

type: "loop" # loops forever
type: "repeat" # alias of loop

type: "loop_pingpong" # loops back and forth
type: "ping_pong" # alias of loop_pingpong
type: "ping-pong" # alias of loop_pingpong
type: "yoyo" # alias of loop_pingpong
type: "loop_yoyo" # alias of loop_pingpong
```

***

## 3. Spawn Animation Triggers

Spawn animations support different trigger modes.

### Immediate Trigger

```yaml
animations:
  trigger: "immediate" # immediate | on_spawn | spawn | on-create | on_create
```

### Delayed Trigger

```yaml
animations:
  trigger: "after_seconds" # after_seconds | after_delay | delay | timer
  delay_seconds: 1.5
```

### After Text Animation Ends

```yaml
animations:
  trigger: "after_text_animation_end" # after_text_animation_end | after_text_end | after_frames_end | after_animation_end
  animation_to_end: "title_anim"
```

***

## 4. Full Example

```yaml
animated_title:
  text: "" # base text, optional if animation frames are used
  offset_x: 0.0
  offset_y: 1.5
  offset_z: -2.0
  scale: 1.0

  animation: # text animation
    enabled: true
    type: "loop"
    interval_ticks: 5
    frames:
      - "A"
      - "B"
      - "C"

  animations: # spawn animation
    trigger: "immediate"
    1:
      type: "play_once"
      duration: 15
      from_y: -0.3
      to_y: 0.0
      from_scale: 0.0
      to_scale: 1.0
    2:
      type: "loop_pingpong"
      duration: 20
      from_y: 0.0
      to_y: 0.05
```

***

## 5. Notes

* `animation` is used for text/frame animation.
* `animations` is used for spawn/transform animation.
* `duration` in `animations` is measured in ticks.
* `interval_ticks` in `animation` is measured in ticks.
* Empty or disabled text animations are ignored safely.
* If `animation` has only 1 frame, that frame is still resolved and used.


---

# 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/hologram-animations.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.