> ## 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.

# Configure PumpkinAnnouncer Announcements and Cooldowns

> Learn the full PumpkinAnnouncer config structure: set cooldowns, define announcements, control world and server filters, and customise plugin messages.

PumpkinAnnouncer stores all its settings in a single YAML file per platform — `paper-config.yml` for Paper and `velocity-config.yml` for Velocity. Both files share the same structure with one small difference: Paper uses the `worlds` key for per-world filtering, while Velocity uses the `servers` key for per-backend-server filtering. The file is generated automatically on first startup with two example announcements you can edit or replace.

## Top-level structure

The config has three top-level sections:

| Section         | Purpose                                                  |
| --------------- | -------------------------------------------------------- |
| `settings`      | Global timer and behaviour options                       |
| `messages`      | All player-facing command responses (fully translatable) |
| `announcements` | Your announcement definitions, keyed by a unique ID      |

## Full annotated example

```yaml theme={null}
settings:
  cooldown-seconds: 60          # Seconds between each announcement broadcast

messages:
  help: "<gradient:gold:yellow><bold>PumpkinAnnouncer</bold></gradient>\n<gray>» <yellow>/pa reload <dark_gray>- <white>Reload config\n<gray>» <yellow>/pa list <dark_gray>- <white>View all IDs\n<gray>» <yellow>/pa test <id> <dark_gray>- <white>Preview an announcement"
  reload-success: "<green>Reload complete! Everything is working correctly."
  list-header: "<gold><bold>Loaded announcements:</bold></gold>"
  id-not-found: "<red>That announcement ID does not exist. Check your config."

announcements:
  welcome_message:
    servers: ["global"]         # Velocity: "global" or a list of backend server names
    worlds: ["global"]          # Paper:    "global" or a list of world names
    sound: "ENTITY_EXPERIENCE_ORB_PICKUP"

    lines:
      - "[center]<gold><bold>Welcome!</bold></gold>"
      - ""
      - "<gray>Visit our store at example.com</gray>"

    actionbar:
      enabled: false
      text: ""
      duration-seconds: 5

    bossbar:
      enabled: false
      text: ""
      color: "BLUE"             # PINK, BLUE, RED, GREEN, YELLOW, PURPLE, WHITE
      style: "PROGRESS"         # PROGRESS, SEGMENTED_6, SEGMENTED_10, SEGMENTED_12, SEGMENTED_20
      duration-seconds: 10
      deplete: true             # Bar drains to empty over the duration
      animated:
        enabled: false
        gradient-colors: ["#A0C4FF", "#BDB2FF"]
        frame-interval-ticks: 3

    title:
      enabled: false
      title: ""
      subtitle: ""
      fade-in-ticks: 10
      stay-ticks: 60
      fade-out-ticks: 10
      animated:
        enabled: false
        gradient-colors: ["#A0C4FF", "#BDB2FF"]
        frame-interval-ticks: 3
```

## The shuffled queue

PumpkinAnnouncer never broadcasts announcements in a fixed order. On startup (and after each `/pa reload`), it builds a list of every announcement ID and shuffles it randomly. The plugin works through the list from top to bottom, firing one announcement per cooldown tick. When the last announcement in the list has played, it reshuffles the entire list and starts again from the beginning.

This means your players see every announcement before any repeats, and the order feels fresh each cycle.

## Server and world filtering

<Tabs>
  <Tab title="Paper (worlds)">
    Use the `worlds` key to restrict an announcement to specific worlds. Players in worlds not on the list will not see the announcement.

    ```yaml theme={null}
    announcements:
      nether_warning:
        worlds: ["world_nether"]   # Only players in the Nether see this
        sound: "ENTITY_GHAST_WARN"
        lines:
          - "[center]<red><bold>⚠ You are in the Nether!</bold></red>"
        actionbar:
          enabled: false
        bossbar:
          enabled: false
        title:
          enabled: false
    ```

    Set `worlds: ["global"]` to broadcast to all worlds.
  </Tab>

  <Tab title="Velocity (servers)">
    Use the `servers` key to restrict an announcement to specific backend servers. The server name must match the name defined in `velocity.toml`.

    ```yaml theme={null}
    announcements:
      voting:
        servers: ["survival", "skyblock"]   # Only players on these backends see this
        sound: "ENTITY_EXPERIENCE_ORB_PICKUP"
        lines:
          - "[center]<gold><bold>Vote for us and earn rewards!</bold></gold>"
        actionbar:
          enabled: false
        bossbar:
          enabled: false
    ```

    Set `servers: ["global"]` to broadcast to all connected servers.
  </Tab>
</Tabs>

## Applying changes

After editing your config, run `/pa reload` from in-game or the console. The command reloads the YAML file, rebuilds the announcement queue, and restarts the broadcast timer — no server restart required.

<Tip>
  All text fields in `messages` and `announcements` support MiniMessage tags, legacy `&` codes, and hex colours. See the [Colors & Formatting](/announcer/colors-and-formatting) page for the full reference.
</Tip>