> For the complete documentation index, see [llms.txt](https://advion.gitbook.io/advion-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://advion.gitbook.io/advion-docs/creating-messages.md).

# ✨ Creating Messages

## ✍️ Creating Custom Messages

UniversalMessages allows you to create an unlimited number of custom messages for Join, Quit, Death, and Kill events. Messages are configured in YAML files located in the `/plugins/UniversalMessages/messages/` folder.

You can create new files or edit existing ones (`join.yml`, `leave.yml`, etc.).

### 📝 General Structure

Every message has a unique ID (the section name) and a set of common settings.

YAML

```
unique_message_id:        # Unique ID (used in database and commands)
  category: JOIN          # Event category: JOIN, QUIT, DEATH, or KILL
  name: "&aMy Message"    # Display name in the GUI
  material: PAPER         # Icon in the GUI
  slot: 10                # Slot in the GUI (0-53)
  page: 1                 # Page number in the GUI
  price: 100              # Cost (0 = free)
  currency: VAULT         # Currency: VAULT or PLAYER_POINTS
  permission: "my.perm"   # (Optional) Permission required to select
  sound: "ENTITY_PLAYER_LEVELUP 1 1" # (Optional) Sound: NAME VOLUME PITCH
```

#### 🔑 Common Fields Explained

* category: Must match the file/event type. Valid values: `JOIN`, `QUIT`, `DEATH`, `KILL`.
* material: The item icon shown in the `/messages` menu. Use standard Bukkit material names (e.g., `DIAMOND_SWORD`, `GOLD_BLOCK`).
* slot: The position of the item in the menu. Slots `0-53` are supported (check `inventories.yml` to avoid overlapping with navigation buttons).
* price & currency:
  * `price`: Amount to deduct.
  * `currency`: `VAULT` (Economy money) or `PLAYER_POINTS` (Points plugin).
* sound: Plays a sound to all players when the message triggers. Format: `SOUND_NAME VOLUME PITCH`.

***

### 🎨 Message Types

The plugin supports 4 visual styles. You define this using the `type` field.

#### 1. CHAT Message

The standard message displayed in the chat box.

* type: `CHAT`
* text: The content of the message.

Example:

YAML

```
join_simple:
  category: JOIN
  type: CHAT
  text: "&e%player% &7has joined the server!"
  material: OAK_SIGN
  slot: 10
```

***

#### 2. ACTIONBAR Message

A text displayed just above the player's hotbar (inventory bar).

* type: `ACTIONBAR`
* text: The content of the message.

Example:

YAML

```
kill_streak:
  category: KILL
  type: ACTIONBAR
  text: "&c⚔ %victim% was obliterated by %killer%!"
  material: IRON_SWORD
  slot: 11
```

***

#### 3. TITLE Message

Large text displayed in the center of the screen, optionally with a subtitle.

* type: `TITLE`
* text: The main big title.
* subtitle: The smaller text below the title.
* title-fade-in: Time to appear (in ticks).
* title-stay: Time to stay on screen (in ticks).
* title-fade-out: Time to disappear (in ticks).

> Note: 20 ticks = 1 second.

Example:

YAML

```
death_wasted:
  category: DEATH
  type: TITLE
  text: "&c&lWASTED"
  subtitle: "&7%player% died tragically"
  title-fade-in: 10
  title-stay: 60
  title-fade-out: 20
  material: REDSTONE_BLOCK
  slot: 12
```

***

#### 4. BOSSBAR Message

A boss health bar displayed at the top of the screen.

* type: `BOSSBAR`
* text: The text displayed above the bar.
* bossbar-color: Color of the bar.
  * *Valid values:* `BLUE`, `GREEN`, `PINK`, `PURPLE`, `RED`, `WHITE`, `YELLOW`.
* bossbar-style: Segmentation style.
  * *Valid values:* `SOLID`, `SEGMENTED_6`, `SEGMENTED_10`, `SEGMENTED_12`, `SEGMENTED_20`.
* bossbar-duration: How long the bar remains visible (in seconds).

Example:

YAML

```
join_boss:
  category: JOIN
  type: BOSSBAR
  text: "&d&l⚔ WARNING: %player% HAS ARRIVED ⚔"
  bossbar-color: PURPLE
  bossbar-style: SEGMENTED_10
  bossbar-duration: 10
  material: DRAGON_HEAD
  slot: 13
```

***

### 🧩 Placeholders

You can use placeholders to make messages dynamic. The plugin supports PlaceholderAPI and internal tags.

#### Internal Placeholders:

| **Placeholder** | **Works In** | **Description**                                                     |
| --------------- | ------------ | ------------------------------------------------------------------- |
| `%player%`      | All Events   | The name of the main player involved (Joining, Quitting, or Dying). |
| `%victim%`      | Death / Kill | Same as `%player%`. Represents the player who died.                 |
| `%killer%`      | Kill         | The name of the player who killed the victim.                       |

> Tip: You can use any PlaceholderAPI tag (e.g., `%server_online%`, `%vault_eco_balance%`) in the `text` and `subtitle` fields.

***

### 🛠️ Advanced: Colors & Gradients

The plugin fully supports modern HEX color codes.

* Standard Colors: `&a`, `&c`, `&l` (Bold), etc.
* HEX Colors: `&#RRGGBB` (e.g., `&#FF0055`).

***

### ⚠️ Important Configuration Rules

1. Unique IDs: Each message section key (e.g., `join_simple`) must be unique across the file.
2. Valid Materials: If you use an invalid material name, it will default to `PAPER` or `BEDROCK` depending on the version.
3. Reloading: After creating or editing a file, use `/um reload` to apply changes immediately.


---

# 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://advion.gitbook.io/advion-docs/creating-messages.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.