Tooltips

Tooltips

Courier’s GUI tooltips use a three-layer system that’s more flexible than it sounds. Instead of hardcoding lore lines, every tooltip is built from configurable names, templates, and reusable fragments — giving you full control over what players see when they hover over items in the mail GUI.

File: config/courier/courier_tooltips.conf

---

The Three Layers

1. Names

The display name (title line) of each GUI element. That bold text at the top of an item tooltip.

names {
  inbox_mail_item = "<!italic>{subject}"
  action_delete = "<!italic><red>Delete"
  action_archive = "<!italic><yellow>Archive"
}

The <!italic> tag disables the default italic styling that Minecraft applies to renamed items.

2. Templates

The lore (tooltip body) — an ordered list of lines. Each line has a type that controls how it renders.

templates {
  action_delete {
    lines = [
      { type = "text", value = "<gray>Move this mail to trash" }
      { type = "blank" }
      { type = "text", value = "<red>Click to delete" }
    ]
  }
}

3. Fragments

Reusable tooltip pieces you can include in any template. Define once, reference everywhere.

fragments {
  "my:custom_footer" {
    lines = [
      { type = "blank" }
      { type = "text", value = "<dark_gray>my.server.com" }
    ]
  }
}

---

Line Types

Each line in a template or fragment has a type that determines how it renders:

Type	Fields	Description
text	value	Static MiniMessage text
blank	(none)	Empty line for spacing
separator	(none)	Decorative separator line
stat	label, value, label-color, value-color	Key-value stat display (e.g., “Sender: Steve”)
progress-bar	label, value, max, filled-color, empty-color	Visual progress bar
fragment	fragment-id	Include a reusable fragment by ID

---

Conditional Display

Lines can be shown or hidden based on mail state using show-if and hide-if:

{ type = "text", value = "<gold>NEW", show-if = "is_unread" }
{ type = "text", value = "<gray>Read", hide-if = "is_unread" }

First line only appears when the mail is unread. Second line appears for everything else. You can build tooltips that adapt to context without needing separate templates.

---

Built-in Fragments

Courier ships with these fragments ready to use:

Fragment ID	Description
courier:separator	Light dotted separator line
courier:separator_heavy	Heavy solid separator line
courier:separator_dots	Dot pattern separator
courier:separator_diamond	Diamond pattern separator
courier:mail_status	Read status and received time
courier:mail_preview	Subject, body preview, and sender
courier:package_info	Package item, Pokemon, and currency counts
courier:action_hint	Yellow action hint text
courier:action_hint_danger	Red action hint text (for destructive actions)
courier:bulk_indicator	”Selected” indicator for bulk operations
courier:unread_badge	Gold “NEW” badge for unread mail
courier:package_badge	”Package Attached” badge

---

Using Fragments in Templates

Use the fragment line type to include any fragment — built-in or custom — in a template:

templates {
  inbox_mail_item {
    lines = [
      { type = "fragment", fragment-id = "courier:mail_preview" }
      { type = "fragment", fragment-id = "courier:separator" }
      { type = "fragment", fragment-id = "my:custom_footer" }
    ]
  }
}

This builds the inbox mail item tooltip by composing three fragments: the built-in mail preview, a separator, and your custom server footer. Fragments nest cleanly — you can build complex tooltips from small, reusable pieces.

---

Custom Fragments

Define your own in the fragments section using any namespace you like:

fragments {
  "my:custom_footer" {
    lines = [
      { type = "blank" }
      { type = "text", value = "<dark_gray>my.server.com" }
    ]
  }

  "my:vip_badge" {
    lines = [
      { type = "text", value = "<gradient:gold:yellow>VIP Mail</gradient>" }
    ]
  }
}

Use "your_namespace:fragment_name" to avoid conflicts with built-in fragments.

---

Tooltip Placeholders

These are available in tooltip text values:

Placeholder	Description
{subject}	Mail subject line
{body_preview}	Truncated mail body preview
{sender_name}	Sender’s display name
{mail_age}	Time since mail was sent (e.g., “2h ago”)
{read_status}	Read/unread status text
{action_text}	Current action hint text
{package_item_count}	Number of items in the package
{package_pokemon_count}	Number of Pokemon in the package
{package_currency_summary}	Currency amounts summary
{recipient_name}	Recipient’s display name
{recipient_online}	Whether the recipient is online
{unread_count}	Number of unread messages
{folder_count}	Number of messages in the current folder
{selected}	Number of selected messages (bulk operations)

You only need to define what you’re changing

Delete a template from courier_tooltips.conf and Courier falls back to its built-in default for that tooltip. Keep only the templates you’ve actually customized — everything else uses sensible defaults automatically.

---

Next Steps

1. GUI Layouts — adjust slot positions and item appearances
2. Messages — customize player-facing text outside of GUIs