# Celebrations: a new rank, said out loud

> When somebody gets a rank - bought, gifted or however you choose - the whole server hears it, louder the higher the rank: a line, a title, fireworks. New in 0.2.7, off by default.

Source: https://stygion.eu/docs/keystone/celebrations
Updated: 2026-11-12

The `celebrate` module, `celebrate.toml`. **Off by default**: an update never decides on its own that a rank is news. Switch it on and write what to celebrate.

## What is celebrated

`ranks` holds a line per group, `group | level | text`:

```toml
ranks = [
  "vip | 1 | &a{player} is VIP now - thank you!",
  "vip-plus | 2 | &b{player} is VIP+!",
  "legend | 3 | &6&l{player} is a LEGEND!",
]
```

- **Level 1** — the line in chat and a sound for everybody.
- **Level 2** — also a title on every screen.
- **Level 3** — also the `fireworks` commands around the player and a second wave of sound.

`{player}` is their name, `{rank}` the group's. Only a group that is new to the player counts. Somebody who is offline when it arrives (bought on the web, say) is celebrated when they next join.

## From where

`sources` says which ways of getting a rank count: `shop`, `vote`, `quest`, `admin`, `playtime`, `config`, `other` — or one exactly as `kind:detail`, such as `other:<key name>` for a shop that grants through the API with its own key. The default is `shop` alone: a rank given by hand or earned by playing is not a purchase.

## Gifts

`gifts` holds a line per group, `group | text`, with `{from}` for who gave it — `vip | &a{player} got VIP from {from}!`. It is used when whatever granted the rank said who it is from (`from` on `POST /v1/players/group`); otherwise the `ranks` line is used. A gift gets the same level, sound and fireworks.

## Sound, fireworks, Discord

- `sounds` — the sound everybody hears at each level, `level | sound` (level-up at 1, the challenge toast at 2 and 3).
- `fireworks` — console commands run at level 3 around the player; the defaults are two fireworks, and anything a console can run works (particles, a sound, a reward).
- `discord-channel` — also post it on Discord: a channel id, `chat` for the bridge's chat room or `events` for its events room. Empty is the game only; needs the Discord module.

All of it is settings and takes effect without a restart. Every setting with its default is in [Every setting](/docs/keystone/settings-reference).
