# Join Messages

A **Join Message** is a custom, styled line broadcast in chat when the player joins the server. It's a full cosmetic type — owned in the vault and equipped from `/cosmetics`.

Join Messages are **opt-in only**. If a player has one equipped, it **replaces** the normal join broadcast. If they have nothing equipped, the player joins in complete silence — no vanilla "X joined the game" text, no filler message, nothing. Only players who actually equipped a Join Message cosmetic broadcast anything.

Delivery bypasses `bukkit.broadcast.user` entirely (the message is sent directly to every online player), so it reaches everyone even on servers whose permission plugin locks that permission down to OPs.

## Configuration (`joinmessages.yml`)

```yaml
join-messages:
  royal:
    display: "&6Royal Entrance"                                   # shown in menus
    value: "&6&l» &fAll hail, &6&l{player} &fhas arrived! &6&l«"  # the broadcast
    icon: GOLDEN_HELMET
    permission: celestial.cosmetics.joinmessage.royal
  sparkle:
    display: "&dSparkle Entrance"
    value: "&#F0F444&l✦ &f{player} &7has entered the realm &#F0F444&l✦"
    icon: NETHER_STAR
    permission: celestial.cosmetics.joinmessage.sparkle
```

| Field | Required | Meaning |
|---|---|---|
| `display` | yes | Name shown in menus |
| `value` | yes | The message broadcast on join. Supports `&` codes, `&#RRGGBB` hex, and `{player}` |
| `icon` | yes | Menu icon material (or `PLAYER_HEAD` + `texture:`) |
| `permission` | no | Defaults to `celestial.cosmetics.joinmessage.<id>` |

### The `{player}` placeholder

Use `{player}` anywhere in `value` and it's replaced with the joining player's name. You can place it more than once, or omit it entirely.

## Presets

The shipped `joinmessages.yml` includes **150+ ready-made entrances** — seasonal (Halloween, Christmas, Easter), themed (pirate, ninja, vampire, robotic, cosmic), gemstone, pride, and gradient/animated styles. Delete the ones you don't want, or add your own following the shape above.

> **Animated styles:** entries whose colors fall in a resource-pack shader trigger range (e.g. the `#F0F0xx` / `#F5F5xx` / `#FAFAxx` / `#FCFCxx` families in the defaults) light up automatically if your pack drives text effects from those hex codes — the same mechanism used by [Rebirth Colors](Cosmetic-Types.md#static-vs-animated-rebirth-styles). With no such pack they simply render as ordinary colored text.

## Equipping

- **Players:** open `/cosmetics`, pick the Join Message category, click one you own.
- **Admins:** `/cosmetics set <player> joinmessage <id>` / `/cosmetics clear <player> joinmessage`.

## See also

[Leave Messages](Leave-Messages) — the same mechanic, mirrored onto the player leaving instead of joining.

---

Next: [Leave Messages](Leave-Messages) · [Chat Emojis](Chat-Emojis.md)