> ## Documentation Index
> Fetch the complete documentation index at: https://pumpkings.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Color Codes and Text Formatting in PumpkinAnnouncer

> PumpkinAnnouncer accepts legacy &codes, hex colors, and MiniMessage in every text field, with support for animated gradients and PlaceholderAPI tokens.

PumpkinAnnouncer accepts every Minecraft color and formatting format in the same text string. You do not need to pick one system — you can mix legacy codes, hex values, and MiniMessage tags on the same line and the plugin resolves them all correctly before delivering the message. This applies to every text field: chat `lines`, `actionbar.text`, `bossbar.text`, `title.title`, and `title.subtitle`.

## Supported color formats

<Tabs>
  <Tab title="Legacy &codes">
    Legacy formatting codes use an ampersand (`&`) followed by a single character. These are the classic Bukkit/Spigot color codes and are fully supported everywhere in PumpkinAnnouncer.

    ```yaml theme={null}
    lines:
      - "&6&lGolden bold text"
      - "&aGreen text &rwith a reset"
      - "&cRed &eand Yellow"
      - "&kObfuscated (matrix) text"
    ```

    | Code                 | Meaning                            |
    | -------------------- | ---------------------------------- |
    | `&0`–`&9`, `&a`–`&f` | Standard 16 colors                 |
    | `&l`                 | Bold                               |
    | `&o`                 | Italic                             |
    | `&n`                 | Underline                          |
    | `&m`                 | Strikethrough                      |
    | `&k`                 | Obfuscated (randomised characters) |
    | `&r`                 | Reset all formatting               |
  </Tab>

  <Tab title="Bungee-style hex">
    Bungee-style hex codes use `&#` followed by a 6-digit hex value. This is the shorthand format popularised by BungeeCord chat plugins.

    ```yaml theme={null}
    lines:
      - "&#FF6B6BRed-pink text"
      - "&#A0C4FFLight blue text"
      - "&#FFD700Gold hex text"
    ```
  </Tab>

  <Tab title="BungeeCord hex">
    BungeeCord's older expanded hex format uses `&x` followed by each hex digit prefixed with `&`. PumpkinAnnouncer translates this format automatically.

    ```yaml theme={null}
    lines:
      - "&x&F&F&0&0&0&0Pure red text"
      - "&x&0&0&F&F&0&0Pure green text"
    ```
  </Tab>

  <Tab title="MiniMessage">
    MiniMessage is the modern Adventure API format and provides the richest feature set, including gradients, click events, hover events, and named colors.

    ```yaml theme={null}
    lines:
      - "<red>Red text</red>"
      - "<color:#FF6B6B>Custom hex</color>"
      - "<gradient:red:gold>Gradient text</gradient>"
      - "<bold>Bold</bold> and <italic>italic</italic>"
      - "<click:open_url:'https://example.com'><hover:show_text:'Click me!'><underlined>Clickable link</underlined></hover></click>"
    ```

    Common MiniMessage tags:

    | Tag                                  | Effect                          |
    | ------------------------------------ | ------------------------------- |
    | `<red>`, `<gold>`, `<green>`, etc.   | Named colors                    |
    | `<color:#RRGGBB>`                    | Arbitrary hex color             |
    | `<gradient:color1:color2>`           | Static gradient across the text |
    | `<bold>`, `<italic>`, `<underlined>` | Text decoration                 |
    | `<reset>`                            | Clear all formatting            |
    | `<click:open_url:'...'>`             | Open a URL on click             |
    | `<hover:show_text:'...'>`            | Show a tooltip on hover         |
  </Tab>
</Tabs>

## Centering chat lines

Prefix any entry in your `lines` array with `[center]` to auto-center that line in chat. PumpkinAnnouncer calculates the pixel width of every character using Minecraft's exact font metrics, strips all color and formatting codes from the width calculation, and inserts the correct amount of leading spaces.

```yaml theme={null}
lines:
  - "[center]<gold><bold>Centered heading</bold></gold>"
  - "[center]<white>This line is also centered."
  - "<white>This line is left-aligned."
```

<Note>
  `[center]` only works in the `lines` (chat) field. ActionBar, BossBar, and Title text are rendered by the client and do not support server-side centering.
</Note>

## Animated gradients

BossBar and Title fields support frame-by-frame animated gradients. Set `animated.enabled: true` and provide a list of hex color stops in `gradient-colors`. PumpkinAnnouncer generates a series of gradient frames by shifting the color stops across the text, then cycles through those frames at the interval you specify.

```yaml theme={null}
bossbar:
  enabled: true
  text: "LIVE EVENT"
  color: "PURPLE"
  style: "PROGRESS"
  duration-seconds: 12
  deplete: false
  animated:
    enabled: true
    gradient-colors: ["#BDB2FF", "#A0C4FF", "#FFDAC1", "#BDB2FF"]
    frame-interval-ticks: 3   # Lower = faster animation (20 ticks = 1 second)
```

```yaml theme={null}
title:
  enabled: true
  title: "WELCOME BACK"
  subtitle: "<gray>Good to see you!</gray>"
  fade-in-ticks: 10
  stay-ticks: 70
  fade-out-ticks: 10
  animated:
    enabled: true
    gradient-colors: ["#FF9A9E", "#FAD0C4", "#FF9A9E"]
    frame-interval-ticks: 4
```

<Tip>
  For a smooth looping animation, repeat the first color as the last entry in `gradient-colors` (e.g., `["#A0C4FF", "#BDB2FF", "#A0C4FF"]`). This creates a seamless loop without a visible jump between cycles.
</Tip>

## PlaceholderAPI (Paper only)

When PlaceholderAPI is installed on your Paper server, any `%placeholder%` token in your text fields is resolved individually for each player before the message is sent. This lets you personalise announcements with data like player names, balances, ranks, or statistics.

```yaml theme={null}
lines:
  - "[center]<gold>Hello, <white>%player_name%<gold>!"
  - "[center]<gray>Your balance: <green>%vault_eco_balance%"

actionbar:
  enabled: true
  text: "<white>Playing as: <aqua>%player_name%"
  duration-seconds: 6
```

PlaceholderAPI tokens are supported in `lines`, `actionbar.text`, `bossbar.text`, `title.title`, and `title.subtitle`.

<Warning>
  PlaceholderAPI is not available on Velocity. Tokens will appear as literal text (e.g., `%player_name%`) if you use them in a `velocity-config.yml`.
</Warning>