跳到主要内容

😀 表情

警告

表情依赖于图像配置，请先阅读 🖼️ 图像 页面。

快速入门​

表情就是一个关键词，玩家输入后会被替换成"图片 + 文本"。最简配置只需两步：

第一步 — 创建底层图像（精灵图最合适）：

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

第二步 — 定义一个指向精灵图某个格子的表情：

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

现在玩家在聊天中输入 :)，它就会被替换成表情图片加上你定义的内容。

接下来的内容逐一展开：怎么自定义内容、怎么按场景切换显示、怎么用模板批量管理、以及兼容性注意事项。

表情配置​

表情配置写在任意包的 emoji: 节点下，每个表情以 命名空间:id 作为唯一标识。

emoji:
  default:time:
    image: default:icons:0:0
    content: "<white><arg:emoji></white>"
    keywords:
      - ':time:'
    permission: emoji.vip           # 可选。使用该表情需要的权限
    chat_completion: true           # 可选。是否出现在客户端补全提示中（默认开启）
字段是否必填说明
keywords是一个或多个触发词。玩家输入任意一个即被替换。
content是替换关键词的 MiniMessage 文本。
image否指向图像某个格子的引用，格式为 命名空间:id:行:列。单格图像直接写 命名空间:id 即可。
permission否使用该表情所需的权限节点。
chat_completion否关键词是否出现在客户端 Tab 补全提示中。默认 true。

内容格式​

arg:emoji 与 arg:keyword 参数​

表情内容中有两个特殊参数可用：

  • <arg:emoji> — 表情的图片字形（由 image 字段解析而来）
  • <arg:keyword> — 触发该表情的第一个关键词
emoji:
  default:time:
    image: default:icons:0:0
    content: "<hover:show_text:'输入 <yellow><arg:keyword></yellow> 使用此表情'><white><arg:emoji></white></hover>"
    keywords:
      - ':time:'

在内容中使用 MiniMessage​

内容完全兼容 MiniMessage——你可以使用颜色、悬浮文字、点击事件、PAPI 占位符、数学表达式，甚至嵌套 <image> 标签：

emoji:
  default:location:
    permission: emoji.location
    image: default:icons:0:0
    content: "<hover:show_text:'使用 <yellow>\"<arg:keyword>\"</yellow> 分享你的坐标'><!shadow><white><arg:emoji></white></!shadow><bold> <papi:player_x>, <papi:player_y>, <papi:player_z></bold></hover>"
    keywords:
      - ':pos:'

复杂内容可以拆成多行——插件会自动拼接：

content:
  - <hover:show_text:'使用 <yellow>"<arg:keyword>"</yellow>'>
  - <!shadow><white><arg:emoji></white></!shadow>
  - "<bold>坐标：<papi:player_x>, <papi:player_y></bold>"
  - </hover>

按场景切换内容​

不同场景（聊天、书、铁砧、告示牌、指令）可能需要不同的显示效果，用 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>"

某个场景没有 override 时，会使用默认的 content。

模板​

当大量表情共享相同的结构时，用模板避免重复：

# 定义模板（只写一次）
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>"

# 应用模板 — 只写不同的部分
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:'

模板提供默认值，overrides 只替换你指定的字段。几十个表情也能干净管理。

配置参考​

config.yml 中的 emoji 部分：

emoji:
  # 表情替换在哪些场景生效
  contexts:
    chat: true
    book: true
    anvil: true
    sign: true

  # 每条消息最多替换多少个表情，防止刷屏卡顿
  max-emojis-per-parse: 16

兼容性​

表情使用 Paper 的现代聊天组件 API 渲染。依赖 Bukkit 旧版聊天事件的插件无法正确显示表情内容。

如果你的聊天插件支持自定义字体（如 TrChat），建议将表情图像的 font 设为自定义字体而非 minecraft:default，这样更安全。