😀 Emoji

caution

Emoji depends on image configurations. Make sure you understand 🖼️ Image first.

Quick Start

An emoji is a keyword that gets replaced with an image + text when a player types it. Here's the minimum setup:

Step 1 — Create the underlying image (a sprite sheet works best):

images:
  default:emojis:
    height: 11
    ascent: 9
    font: minecraft:default
    file: minecraft:font/image/emojis.png
    grid_size: 4,4

Step 2 — Define an emoji that points to a cell in that sprite sheet:

emoji:
  default:smiley:
    image: default:emojis:0:0
    content: "<!shadow><white><arg:emoji></white></!shadow>"
    keywords:
      - ':smiley:'
      - ':)'

Now when a player types :) in chat, it gets replaced with the emoji image followed by the content.

---

The rest of this page covers content customization, context-specific overrides, templates, and compatibility.

Emoji Configuration

An emoji entry lives under emoji: in any pack config. Each emoji has a unique ID in namespace:id form.

emoji:
  default:time:
    image: default:icons:0:0
    content: "<white><arg:emoji></white>"
    keywords:
      - ':time:'
    permission: emoji.vip           # Optional. Permission required to use
    chat_completion: true           # Optional. Show in tab-completion (default: true)

Field	Required	Description
keywords	Yes	One or more trigger strings. When a player types one, it gets replaced.
content	Yes	The MiniMessage text that replaces the keyword.
image	No	A reference to an image cell in namespace:id:row:column format. If your image has a single cell, namespace:id is enough.
permission	No	Permission node required to use this emoji.
chat_completion	No	Whether the keywords appear in client-side tab completion. Defaults to true.

Content Formatting

The arg:emoji and arg:keyword Parameters

Two special parameters are available inside emoji content:

• <arg:emoji> — the image glyph itself (resolved from your image field)
• <arg:keyword> — the first keyword that triggered this emoji

emoji:
  default:time:
    image: default:icons:0:0
    content: "<hover:show_text:'Type <yellow><arg:keyword></yellow> to use this emoji'><white><arg:emoji></white></hover>"
    keywords:
      - ':time:'

MiniMessage in Content

Content is fully MiniMessage-compatible — you can use colors, hover text, click events, PAPI placeholders, math expressions, and nested <image> tags:

emoji:
  default:location:
    permission: emoji.location
    image: default:icons:0:0
    content: "<hover:show_text:'Use <yellow>\"<arg:keyword>\"</yellow> to share your location'><!shadow><white><arg:emoji></white></!shadow><bold> <papi:player_x>, <papi:player_y>, <papi:player_z></bold></hover>"
    keywords:
      - ':pos:'

For complex content, split into multiple lines — the plugin auto-joins them:

content:
  - <hover:show_text:'Use <yellow>"<arg:keyword>"</yellow>'>
  - <!shadow><white><arg:emoji></white></!shadow>
  - "<bold>Location: <papi:player_x>, <papi:player_y></bold>"
  - </hover>

Context-Specific Overrides

Different chat contexts (chat, book, anvil, sign, command) may need different formatting. Use content_overrides:

emoji:
  default:time:
    image: default:icons:0:0
    content: "<!shadow><white><arg:emoji></white></!shadow>"
    keywords:
      - ':time:'
    content_overrides:
      chat: "<hover:show_text:'<l10n:emoji.tip:\"<arg:keyword>\":\"<arg:emoji>\">'><!shadow><white><arg:emoji></white></!shadow></hover>"
      book: "<hover:show_text:'<arg:keyword>'><!shadow><white><arg:emoji></white></!shadow></hover>"
      anvil: "<!i><!shadow><white><arg:emoji></white></!shadow></!i>"

When a context has no override, the default content is used.

Templates

When you have many emojis sharing the same content structure, use a template to avoid repetition:

# Define the template once
templates:
  default:emoji/basic:
    content: "<!shadow><white><arg:emoji></white></!shadow>"
    content_overrides:
      chat: "<hover:show_text:'<l10n:emoji.tip:\"<arg:keyword>\":\"<arg:emoji>\">'><!shadow><white><arg:emoji></white></!shadow></hover>"
      book: "<hover:show_text:'<arg:keyword>'><!shadow><white><arg:emoji></white></!shadow></hover>"
      anvil: "<!i><!shadow><white><arg:emoji></white></!shadow></!i>"

# Apply the template — only specify what differs
emoji:
  default:smiley:
    template: default:emoji/basic
    overrides:
      image: default:emojis:0:0
      permission: emoji.smile
      keywords:
        - ':smiley:'
        - ':)'

  default:angry:
    template: default:emoji/basic
    overrides:
      image: default:emojis:0:1
      permission: emoji.angry
      keywords:
        - ':angry:'

The template provides defaults; overrides replaces only the fields you specify. This scales cleanly to dozens of emojis.

Configuration Reference

The emoji section in config.yml:

emoji:
  # Where emoji replacement runs
  contexts:
    chat: true
    book: true
    anvil: true
    sign: true

  # Caps the number of emoji replacements per message to prevent lag
  max-emojis-per-parse: 16

Compatibility

Emojis are rendered using Paper's modern chat component API. Plugins relying on Bukkit's legacy chat events will not display emoji content correctly.

The plugin also needs the correct font in chat. If your chat plugin supports custom fonts (like TrChat), set your emoji image's font to a custom font instead of minecraft:default for better security.