✏️ 文本格式

MiniMessage

物品名称、工具提示和 GUI 等文本内容均使用 MiniMessage 格式。完整语法请参阅 MiniMessage 官方文档。

任何有意义的标签都可以在其生效的位置被转义。在纯文本中，标签起始字符（<）可以通过前置反斜杠（\）进行转义。在带引号的字符串中，起始引号字符（' 或 "）也可以被转义。在这两种情况下，转义符本身也可以被转义以输出字面上的反斜杠。为简单起见，未加引号的标签参数不能使用转义字符。在不支持转义的上下文中，转义字符会作为普通字符原样输出。在支持转义的上下文中，如需输出反斜杠，应通过双反斜杠（\\）来实现。

注意事项

危险

语法说明中的 <命名空间>、<路径> 和 [行] 等文字是参数占位符，使用时应替换为实际值，不要原样复制尖括号或方括号。标签名称本身包含的 _ 则必须保留。

例如，%image_mm_<命名空间>:<路径>% 中的图片若定义为 default:icons，实际应写成 %image_mm_default:icons%。

以下是几个例子：

• %image_mm_<default>:<icons>% ❌️（应该去掉 < 和 >）
• %image_mm_default:icons% ✔️
• %image_mm_default:icons:[行]:[列]% ❌️（如果你不需要行和列，请删除这两个参数）
• %image_mm_default:icons:[0]:[1]% ❌️（应该去掉 [ 和 ]）
• %imagemmdefault:icons:1:0% ❌️（不能去掉标签名称中的 _）
• %image_mm_default:icons:1:0% ✔️
• id: <test_namespace>:<test/my_path> ❌️（应该去掉 < 和 >）
• id: test_namespace:test/my_path ✔️
• <shift:_666_> ❌️（应该去掉 _）
• shift:666 ❌️（缺少标签外层的 < 和 >）
• <viewerarg:player.name> ❌️（不能去掉标签名称中的 _）
• <shift:666> ✔️

附加标签

以下是插件提供的其他可用标签。

提示

[_参数_] 表示该参数是可选的。

信息

可以用 ' 或 " 包裹参数，例如 <papi:'exp_multiplier':'1'>。

标签也可以嵌套使用，例如 <expr:'0.##':'<papi:exp_multiplier:1> * 10'>。

信息

部分标签以 viewer_ 开头，用于区分文本查看者与事件主体。某些场景中的文本会同时使用这两类上下文，例如：

message: -|
  嗨，<viewer_arg:player.name>。
  你有没有注意到 <arg:player.name> 与一个自定义方块进行了交互？

当玩家 A与自定义方块交互并触发消息广播时，玩家 B看到的内容为：

“嗨，B。你有没有注意到 A 与一个自定义方块进行了交互？”

<shift:_像素值_>

shift 用于插入插件提供的偏移字符。

item_name: "<!i><shift:-100><#FF8C00>黄玉钓竿"

<papi:_占位符_:[_默认值_]>

<viewer_papi:_占位符_:[_默认值_]>

<rel_papi:_占位符_:[_默认值_]>

papi 用于解析 PlaceholderAPI 提供的占位符。

提示

rel_papi 指的是关系型占位符。

item_name: "<!i><#FF8C00><papi:player_name>的黄玉钓竿"

你还可以通过指定默认值，让这些标签在更多场景下安全使用而不会报错，例如：

functions:
  - type: drop_exp
    count:
      type: uniform
      min: "<papi:exp_multiplier:1> * 3"
      max: "<papi:exp_multiplier:1> * 5"

<image:_命名空间_:_路径_:[_行_]:[_列_]:[_格式_]>

<image:_命名空间_:_路径_:[_格式_]>

image 用于插入插件中已注册的图片。

item_name: "<!i><white><image:default:icons><#FF8C00>黄玉钓竿"

item_name: "<!i><white><image:default:icons:0:1><#FF8C00>黄玉钓竿"

item_name: "<!i><red><image:default:icons:'<!shadow><white>'> 黄玉钓竿"

item_name: "<!i><red><image:default:icons:0:1:'<!shadow><white>'> 黄玉钓竿"

<i18n:_标识符_>

查找适用于当前服务端语言的翻译。

items:
  custom:chinese_lantern:
    material: paper
    data:
      item_name: "<i18n:item.chinese_lantern>"

<l10n:_标识符_>

查找适用于当前客户端语言的翻译。

items:
  custom:chinese_lantern:
    material: paper
    data:
      item_name: "<l10n:item.chinese_lantern>"

<expr:_格式_:_表达式_>

进行一些数学运算

item_name: "<!i><#FF8C00><expr:0.##:'70 / 8'>"

item_name: "<!i><#FF8C00><expr:0.##:'<papi:player_x> / 8'>"

将格式写为 bool 可把结果输出为 true / false（非零即为 true）：

- "<expr:bool:'<papi:farming_level> >= 10'>"

提示

常用链接

https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/text/DecimalFormat.html

https://github.com/Xiao-MoMi/sparrow-expression

<random:_标识符_>

<random:_标识符_:_类型_:[参数..._]>

生成一个随机数。在同一上下文中，相同 id 始终返回首次生成的值，不同 id 则各自独立生成。

lore:
  - "<!i>攻击力: <random:atk:5~10>"
  - "<!i>暴击率: <random:crit:triangle:0:100:80>%"

支持的分布类型（参数为位置参数，[...] 可省略）：

类型	参数
uniform	min, max
triangle	min, max, [mode]（默认为中点）
normal / gaussian	min, max, [mean], [std_dev], [max_attempts]
log_normal	min, max, [location], [scale], [max_attempts]
skew_normal	min, max, skewness, [mean], [std_dev], [max_attempts]
binomial	trials, probability
exponential	mean, [min], [max]
beta	[min], [max], [alpha], [beta]
fixed / constant	value

简写：<random:id:5~10> 等同于 uniform:5:10；<random:id:7> 为常量。各分布的详细说明见数字格式。

警告

分布会在首次生成随机值时绑定。在同一上下文中，如果同一个 id 使用了不同分布，则只有首次指定的分布生效。

<arg:_索引_>

仅用于 translations 目录下的文件，表示索引参数。

<arg:_标识符_>

<viewer_arg:_标识符_>

这是一个命名参数，其值可以来自以下两种来源：

1. 上下文特定的参数 – 这些是在当前上下文中明确传递的参数。

internal.cooking_info.0: "时间：<arg:cooking_time>刻"
internal.cooking_info.1: "经验：<arg:cooking_experience>"

2. 通用参数

由 <random:xxx> 标签（或带 id 的 random 条件）生成的命名随机值，可以在同一上下文中通过链式参数读取：

<arg:random.xxx>  # 读取此上下文中已生成的命名随机值

3. 上下文主体 – 如果上下文主体（例如，一个玩家）提供了参数。查看此页面了解更多：

提示

某些场景中可能同时存在多个上下文主体。访问不同主体的参数，可以精确控制函数的作用范围和行为。

# 在方块的位置生成粒子
- type: particle
  x: '<arg:block.x> + 0.5'
  y: '<arg:block.y> + 0.5'
  z: '<arg:block.z> + 0.5'
  ...
# 在玩家的位置生成粒子
- type: particle
  x: '<arg:player.x>'
  y: '<arg:player.y>'
  z: '<arg:player.z>'
  ...
# 广播消息
- type: message
  target: 'all'
  message:
    - "你好，<viewer.arg:player.name>！这条消息来自 <arg:player.name>。"
    - "<arg:player.name> 刚刚与 <arg:block.owner> 方块进行了交互！"

<var:_变量名_>

读取当前上下文中由 set_variable 函数创建的变量。

type: run
functions:
  - type: set_variable
    name: multiplier
    value_type: double
    value: 1.5
  - type: message
    message: "当前倍率：<var:multiplier>"

数字变量用于表达式时会保持数字类型。例如，在数字字段中，<var:multiplier> * 10 的计算结果为 15。字符串变量可以包含其他上下文标签，这些标签会在读取变量时解析。

变量的作用域仅限一次执行上下文。变量必须先设置再读取，读取不存在的变量会报错。配置中定义的全局文本请使用 <global:id>。

<global:_标识符_:[参数...]>

在配置中定义的全局变量。

item_name: "<global:rare_tag> 稀有三叉戟"

<bubble:_id_:_left_:_right_> (需要 CustomNameplates)

创建带有气泡的文字

item_name: "<bubble:chat_1:1:1:'<black><!shadow>What Happened'>"

<nameplate:_id_:_left_:_right_:> (需要 CustomNameplates)

item_name: "<nameplate:xmas:1:1:'ABCDEFG'>"

创建带有铭牌的文字

<background:_id_:_left_:_right_:> (需要 CustomNameplates)

创建带有背景的文字

item_name: "<background:bedrock_1:1:1:'ABCDEFG'>"