原始JSON文本(Raw JSON Text)是Minecraft用于给玩家发送并显示富文本的格式。原始JSON文本使用JSON编写。
Java版[]
原始JSON文本由聊天组件(Chat Component)组成。根组件可包含有子组件,而子组件也可以有自己的子组件。组件可以包含格式和交互事件,这些也会应用到他们的子组件上。
聊天组件可以使用除“null”外的所有JSON数据类型。数值和布尔值将会视为字符串处理,而字符串和数组用于简写较长的对象结构,见下文所述。
- 含有纯文本的字符串。与只有标签 text的对象效果相同。例如,
"A"
和{"text": "A"}
等价。 - 布尔值将会转换为字符串直接显示。与只有标签 text的对象效果相同。例如,
true
、"true"
和{"text": "true"}
等价。 - 数值将会转换为字符串直接显示。与只有标签 text的对象效果相同。例如,
1.9E10
、"1.9E10"
和{"text": "1.9E10"}
等价。 - 含有多个聊天组件对象的列表。与含有 extra数组的聊天组件效果相同。[注 1]例如,
["A", "B", "C"]
和{"text": "A", "extra": ["B", "C"]}
等价。 - 一个聊天组件对象。所有非内容标签都是可选的。
- 内容
- 一个对象需要包含内容标签才能生效。不同的内容类型及它们对应的标签将于下方说明。可以含有多个内容标签,但最终只有一个会生效。[注 2]
- type:可选,用于提升解析与错误检查的速度。有效值有:
text
、translatable
、score
、nbt
、keybind
。[新增:JE 1.20.3] - 子对象
- extra:含有在此组件之后显示的附加聊天组件的列表。
- 子聊天组件。除非额外指定,子组件将继承父组件的所有格式和交互事件。
- 格式
- color:渲染文字时使用的颜色。有效值有:
black
、dark_blue
、dark_green
、dark_aqua
、dark_red
、dark_purple
、gold
、gray
、dark_gray
、blue
、green
、aqua
、red
、light_purple
、yellow
、white
、reset
(取消父对象使用的颜色效果)。
设置为"#<hex>"
可以使用以6位十六进制RGB颜色格式定义的颜色。 - font:渲染文字时使用的字体的资源路径。使用的字体在
assets/<namespace>/font
里定义,默认为minecraft:default
。 - bold:是否将文字渲染为粗体。
- italic:是否将文字渲染为斜体。原本为斜体的自定义物品名称可以通过将此值设置为“false”来取消斜体。
- underlined:是否为文字添加下划线。
- strikethrough:是否为文字添加删除线。
- obfuscated:是否将文字混淆处理。
- 交互事件
- insertion:玩家按住⇧ Shift并点击文字时,填入聊天框的的文字。其不会覆盖聊天框内原有的文字。仅在聊天页面中生效。
- clickEvent:允许在玩家点击文字时产生事件。若无附加说明,其仅在聊天页面和成书中生效。
- action:点击后发生的事件。有效值有:
- “open_url”:在默认浏览器中将 value作为URL地址打开。
- “open_file”:打开计算机上位于 value的文件。其用于游戏自动生成的信息中(如截图后显示的信息),且出于安全原因禁止玩家使用。
- “run_command”:执行一条命令。可用于告示牌上,但仅支持在父组件中使用;通过使用告示牌触发。在聊天页面和成书中触发则会以玩家的身份和位置执行命令,但需要玩家拥有相应的权限;命令必须拥有“/”前缀,且不能为聊天命令(
/say
、/tell
和/teammsg
)。在告示牌中,命令将由服务器在告示牌所在的位置执行,并将使用告示牌的玩家视为执行者。因为命令由服务器执行,告示牌命令的权限等级与命令方块相同,玩家的权限等级会被忽略;且其不受聊天框长度的限制,可以省略“/”前缀。 - “suggest_command”:打开聊天页面并输入 value。若聊天框已有内容,其将会被覆盖。在成书中无效。[1]
- “change_page”:仅在成书中生效。若指定页面存在,将成书翻至第 value页。
- “copy_to_clipboard”:将 value复制到剪贴板中。
- value:指定的URL、文件路径、信息、命令或页码。
- action:点击后发生的事件。有效值有:
- hoverEvent:允许在玩家将鼠标悬停在文本上时显示提示文字。
- action:提示文字的类型。有效值有:
- “show_text”:显示一个聊天组件。
- “show_item”:显示一个物品的工具提示。与在物品栏中悬浮在物品上时出现的工具提示相同。
- “show_entity”:显示实体的名称、类型和UUID。用于 selector中。
- contents:此标签的格式取决于 action的值。
- “show_text”:一个聊天组件。可以使用字符串、数组或对象。
- “show_item”:要显示的物品。
- id:物品的命名空间物品ID。若无效则视为
minecraft:air
。 - count:可选,物品的数量。
- tag:可选,物品的NBT标签。参见player.dat格式#物品结构。
- id:物品的命名空间物品ID。若无效则视为
- “show_entity”:要显示的实体。
- name:可选,若未指定则隐藏本参数。将显示为实体名称的聊天组件。
- type:指定实体的类型。应为一个命名空间实体ID。若无效则视为
minecraft:pig
。 - id:指定实体的UUID。应为一个有效的由连字符连接的十六进制UUID或4个整型值所构成的整型数组UUID。
[新增:JE 1.20.3]
value:此标签的格式取决于 action的值。已弃用,请使用 contents代替。- “show_text”:一个聊天组件。可以使用字符串、数组或对象。
- “show_item”:一个物品的NBT标签。参见player.dat格式#物品结构。
- “show_entity”:一个NBT标签。其不包含所有的实体数据,仅储存实体的名称、类型和UUID。
- name:可选,若未指定则隐藏本参数。指定该实体的名称并显示。包含将被解析聊天组件的JSON文本。若字符串无法被解析为聊天组件,整个提示文字会显示为“无效的实体!”。
- type:可选,若未指定则隐藏本参数。指定该实体的类型。包含将视为实体类型的纯文本,可以为任何文字。
- id:可选,若未指定则显示为空行。指定该实体的UUID。包含将视为UUID的纯文本,可以为任何文字。
- action:提示文字的类型。有效值有:
由于 extra标签的存在,以上格式可递归嵌套成非常复杂与多样的文本。然而,原始JSON文本不必弄得如此复杂:几乎所有的标签都是可选的。
内容类型[]
聊天组件可以显示多种类型的内容。这些标签应直接包含于聊天组件对象中。
纯文本[]
显示纯文本。
- 聊天组件。
- text:一段文本。里面的内容会进行转义。
已翻译文本[]
以当前语言显示一段已翻译的文本。使用的语言取决于客户端选择的语言,所以不同客户端在收到同一服务器的同一翻译标识符后,客户端会使用各自的语言显示文本。若在客户端内未找到对应的译文,则会检查en_us.json
中对应的译文。若依旧未找到,则输出 fallback的值或直接输出翻译标识符本身。
翻译标识符可以在资源包的语言文件内指定。也可以使用游戏内置资源包内的翻译标识符。
翻译标识符指向的译文、翻译标识符本身和 fallback可以包含应用于未知文本的变量。变量通常会以%s
(显示列表中的下一个对象)或%1$s
(显示列表中的第1个对象;可以将1
替换为其他数字,对应列表中的第N个对象)的形式出现。[注 3]显示已翻译文本时,这些变量将由 with提供的聊天组件列表填充。
如果未给某变量提供参数,输出的文本会将所有变量按原样输出,不使用 with提供的值。
- 聊天组件。
- translate:一个翻译标识符。
- fallback:可选,翻译标识符无对应译文时输出的文本。不存在 translate时忽略。
- with:可选,含有用于替换译文内变量的聊天组件的列表。不存在 translate时忽略。
- 一个聊天组件。
记分板分数[]
显示实体在记分板中某个记分项的分数。
需要解析组件。 |
---|
此标签会解析为值为记分板分数的 text标签。 |
实体名称[]
显示由目标选择器找到的实体的名称。
若选择器发现了一个实体,则会显示这个实体的名称。若发现了多个实体,则会显示所有被选中的实体的名称,用分隔符(默认为灰色的半角逗号)分隔。若没有发现实体,则不会显示任何文本。
悬浮在名称上时会显示包含名称、类型和UUID的工具提示。点击一个玩家的名称会出现私信该玩家的命令建议;按住⇧ Shift点击玩家名称会将其名称填入聊天框中;按住⇧ Shift点击非玩家实体的名称会将其UUID填入聊天框中。
需要解析组件。 |
---|
|
- 聊天组件。
- selector:一个目标选择器。
- separator:可选,用作分隔符的聊天组件。默认为
{"color": "gray", "text": ", "}
。在组件显示多个实体时,使用此标签指定的聊天组件分隔各个实体的名称。
按键绑定[]
显示可设置键位的动作当前绑定的键位的名称。其取决于客户端的绑定配置,所以不同客户端在收到同一服务器的同一标识符后,客户端会使用各自的配置显示键位名称。
例如,若使用默认配置,{"keybind": "key.inventory"}
将显示为“e”。
- 聊天组件。
- keybind:一个键位标识符。
NBT标签值[]
如果NBT标签的值为字符串,则显示它的内容;其他值则将显示为SNBT。如果 interpret为真,游戏会尝试将获取的值解析为聊天组件并显示。因为JSON和SNBT之间并不相通,这种解析通常只在值为字符串时成功。如果 interpret为真且解析失败,则不会显示任何文本。如果发现多个值(通常由选择了多个对象或路径会选择多个值造成),则会显示所有值,用分隔符(默认为半角逗号)分隔。
需要解析组件。 |
---|
|
- 聊天组件。
- nbt:一段NBT路径,用于指定NBT标签。需要同时存在 block、 entity或 storage。可以含有多个相应标签,但只会有一个生效。[注 5]
- interpret:可选,默认为“false”。若指定为“true”,则会将获取到的每个值视为聊天组件并解析。不存在 nbt时忽略。
- separator:可选,用作分隔符的聊天组件。默认为
{"text": ", "}
。在组件显示多个值时,使用此标签指定的聊天组件分隔各个值。 - block:一个坐标,指定要获取NBT标签的方块实体。坐标可以是绝对坐标、相对坐标或局部坐标。不存在 nbt时忽略。
- entity:一个目标选择器,指定要获取NBT标签的实体。不存在 nbt时忽略。
- storage:一个命名空间ID,指定要获取NBT标签的命令存储。不存在 nbt时忽略。
解析组件[]
部分聊天组件不会一直存在。含有 score、 selector或 nbt标签的组件会被解析:从世界中取得指定数据,将数据转化为相应的聊天组件,之后用转化后的组件替换原来的组件。解析会通过放置告示牌、第一次打开成书、将成书置于讲台上和使用命令完成。它也可以通过物品修饰器“set_name”和“set_lore”完成,但同时需要物品修饰器含有 entity标签。在自定义名称中无法解析这些组件。
此外,解析会固定获取的值。因此,这些组件的内容不再变化,不会因环境的变化而调整相应值。
基岩版[]
- 根标签。
- rawtext:包含所有文本对象的列表。
- :基础聊天对象。
- text:直接显示原始文本的字符串。存在 translate时忽略。
- selector:发送后转换为实体名称的目标选择器。
- translate:将以所选语言显示的本地化键名。语言文件中可找到所有有效的本地化键名。
- with:与 translate配合使用,以此列表内容替换翻译字符串中的参数。
- :参数将替换为的内容,按顺序对应(如:列表中的第一个元素对应 translate中的
%%1
)。
- :参数将替换为的内容,按顺序对应(如:列表中的第一个元素对应 translate中的
- score:显示记分项内指定实体的分数。
- name:指定一个分数持有者,可使用“@s”、“@a”等目标选择器或虚拟玩家名,与 selector无关。如果为
*
,则显示阅读者分数(如:/tellraw @a {"rawtext":[{"score":{"name":"*","objective":"obj"}}]}
会向在线玩家显示自己在“obj”记分项的分数)。 - objective:指定要显示记分项的名称。
- name:指定一个分数持有者,可使用“@s”、“@a”等目标选择器或虚拟玩家名,与 selector无关。如果为
- :基础聊天对象。
- rawtext:包含所有文本对象的列表。
历史[]
关于“原始JSON文本格式”的历史,请见各版本页面。
关于“原始JSON文本格式”的历史,请见各版本页面。
关于“原始JSON文本格式”的历史,请见各版本页面。
关于“原始JSON文本格式”的历史,请见各版本页面。
关于“原始JSON文本格式”的历史,请见各版本页面。
关于“原始JSON文本格式”的历史,请见各版本页面。
关于“原始JSON文本格式”的历史,请见各版本页面。
关于“原始JSON文本格式”的历史,请见各版本页面。
关于“原始JSON文本格式”的历史,请见各版本页面。
关于“原始JSON文本格式”的历史,请见各版本页面。
关于“原始JSON文本格式”的历史,请见各版本页面。
关于“原始JSON文本格式”的历史,请见各版本页面。
关于“原始JSON文本格式”的历史,请见各版本页面。
关于“原始JSON文本格式”的历史,请见各版本页面。
关于“原始JSON文本格式”的历史,请见各版本页面。
关于“原始JSON文本格式”的历史,请见各版本页面。
关于“原始JSON文本格式”的历史,请见各版本页面。
关于“原始JSON文本格式”的历史,请见各版本页面。
关于“原始JSON文本格式”的历史,请见各版本页面。
关于“原始JSON文本格式”的历史,请见各版本页面。
关于“原始JSON文本格式”的历史,请见各版本页面。
关于“原始JSON文本格式”的历史,请见各版本页面。
关于“原始JSON文本格式”的历史,请见各版本页面。
关于“原始JSON文本格式”的历史,请见各版本页面。
参见[]
备注[]
- ↑ 请注意,之后的组件将视为第一个组件的子组件,因此第一个组件的格式和交互事件将应用于之后的组件。例如,
[{"text": "A", "color": "red"}, "B", "C"]
将会输出都被渲染为红色的文本。 - ↑ 按照 text、 translate、 score、 selector、 keybind、 nbt的顺序检查。若提供了多个内容标签,则会使用此列表中最靠前的标签。
- ↑ 选择“下一个”对象时忽略已索引变量。所以若译文“Hello %s, %2$s, and %s.”被赋予参数“John”和“Becky”,它将显示为“Hello John, Becky, and Becky.”
- ↑ 显示读者自己的分数仅在发送的信息不会被不同玩家同时阅读时生效。显示在聊天信息、
/title
或被独自阅读的成书上时会生效,但在告示牌、讲台上的成书等地方将无法生效。 - ↑ 按 block、 entity、 storage的顺序检查。若提供了多个标签,则会使用此列表中最靠前的标签。
参考[]
版本 | |||||||
---|---|---|---|---|---|---|---|
开发周期 |
| ||||||
技术 |
| ||||||
多人游戏 | |||||||
游戏订制 |
版本 |
| ||||||
---|---|---|---|---|---|---|---|
开发 |
| ||||||
技术性 | |||||||
多人游戏 | |||||||
特色功能 |
语言