原始JSON文本(Raw JSON Text)是Minecraft用于给玩家发送并显示富文本的格式,它也可以通过命令和数据包发送。原始JSON文本使用JSON编写。
Java版
原始JSON文本由聊天组件组成。结构本身只有一个根对象,但这个根对象可包含有子对象,而这些子对象也可以有自己的子对象,依此类推。对象可以包含格式和交互事件,这些也会应用到他们的子对象上。
聊天组件的格式可以是JSON字符串、JSON数组或JSON对象。字符串和数组用于简写较长的对象,见下文所述。
聊天组件内存在的数值和布尔值将会视为字符串处理。
- 直接显示原始文本的字符串。与只有标签 text的对象效果相同。例如,
"A"
和{"text": "A"}
是等价的。 - 包含多个文本对象的列表。与含有 extra数组的文本对象效果相同。[1]例如,
["A", "B", "C"]
和{"text": "A", "extra": ["B", "C"]}
是等价的。 - 一个聊天组件。若要生效,则必须包含内容组件:text、translate、score、selector、keybind或nbt。含有多个组件是允许的,但只会有一个生效。[2]其他组件是可选的。
- 内容:纯文本
- text:直接显示原始文本。里面的内容会进行转义。
- 内容:已翻译文本
- translate:包含翻译标识符的字符串,会以玩家所选择的语言显示对应的文字。若未找到对应的译文,则会检查
en_us.json
中对应的译文。若依旧未找到,则直接输出标识符。标识符与从assets文件夹或资源包中找到的语言文件的标识符一致。 - with:可选。列表内的参数将为译文中的变量赋值。不存在 translate时忽略。
- 译文可以包含使用于未知文本的变量。这些变量直接在标识符中定义,与JSON对象无关。变量通常会以
%s
(显示下一个参数)或%1$s
(显示第1个参数;可以将1
替换为其他数字,对应指定的其他参数)的形式出现。[3]如果未给某变量提供参数,该变量将不会显示。
- 译文可以包含使用于未知文本的变量。这些变量直接在标识符中定义,与JSON对象无关。变量通常会以
- 内容:记分板的值(需要解析)
- score:显示一个持有者在指定记分项下当前的分数。若指定持有者或记分项不存在,或持有者未被记分项追踪则不会显示任何内容。
- name:要被显示分数的持有者。可使用指定名称、选择器或“*”。若为选择器,则选择器不能选择多个实体。若为
*
,则会显示读者自己的分数(例如,/tellraw @a {"score":{"name":"*","objective":"obj"}}
将给每个在线玩家显示他们自己在“obj”目标里的分数)。[4] - objective:要显示分数的记分项的内部名称。
- value:可选。如果存在,将以此参数的值覆盖目标原先的分数。
- name:要被显示分数的持有者。可使用指定名称、选择器或“*”。若为选择器,则选择器不能选择多个实体。若为
- 内容:实体名称(需要解析)
- selector:包含目标选择器的字符串,显示被选中玩家和实体的名称。若选择器发现了多个实体,则会显示所有被选中的实体的名称,用半角逗号分隔。悬浮在名称上时会显示包含名称、类型和UUID的工具提示;点击一个玩家的名称会出现私信该玩家的命令建议;按住⇧ Shift点击玩家名称会将其名称填入聊天框中;按住⇧ Shift点击非玩家实体的名称会将其UUID填入聊天框中。
- 内容:按键键位
- keybind:包含键位标识符的字符串,会显示某操作当前绑定的按钮的名称。例如,若使用默认配置,
{"keybind": "key.inventory"}
将显示“e”。 - 内容:NBT的值(需要解析)
- nbt:包含一段NBT路径的字符串,用于从实体、方块或存储处查找指定NBT数据标签的值。若值为字符串,则显示它的内容;其他值将显示为SNBT,没有空格和换行符。若值为聊天组件,显示方式受 interpret影响。若发现多个值(通常由选择了多个对象或路径会选择多个值造成),则会显示所有值,之间用半角逗号分隔。需要同时存在block、entity或storage。含有多个组件是允许的,但只会有一个生效。[5]
- interpret:可选,默认为“false”。若指定为“true”,则会尝试将获取到的每个值视为原始JSON文本聊天组件并解析。若解析失败,则不会显示任何内容。不存在 nbt时忽略。
- block:指定要获取NBT数据标签的方块实体的坐标。坐标可以是绝对坐标或相对坐标。不存在 nbt时忽略。
- entity:以目标选择器的形式指定要获取NBT数据标签的实体。不存在 nbt时忽略。
- storage:指定要获取NBT数据标签的命令存储的命名空间ID。不存在 nbt时忽略。
- 子对象
- extra:包含在文本之后显示的附加原始JSON文本对象的列表。
- 子文本对象。子对象将继承父对象的所有格式和交互事件,除非额外指定。
- 格式
- 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位十六进制颜色格式定义的颜色。 - bold:可选。是否将文字渲染为粗体。
- italic:可选。是否将文字渲染为斜体。原本为斜体的自定义物品名称也可以通过将此值设置为“false”来取消斜体。
- underlined:可选。是否为文字附加下划线。
- strikethrough:可选。是否为文字附加删除线。
- obfuscated:可选。是否将文字模糊处理。
- font:可选。使用在
assets/<namespace>/font
里定义的字体渲染文本。默认为minecraft:default
。 - separator [新增:1.17]:可选。替换在显示多个值时使用的符号(默认为“,”)。可以为字符串或另一个聊天组件。
- 交互事件
- insertion:可选。当玩家按住⇧ Shift并点击文字时,此组件指定的字符串会自动填入聊天框中,不会覆盖原有的文字。仅在聊天页面中生效。
- clickEvent:可选。允许在玩家点击文字时产生事件。若无附加说明,仅在聊天页面和成书中生效。
- action:点击时发生的事件。有效值有:
- “open_url”:在默认浏览器中打开 value中的URL地址。
- “open_file”:打开计算机上位于 value的文件。其用于游戏自动生成的消息中(如截图时显示的信息),且出于安全原因禁止玩家使用。
- “run_command”:可用于告示牌上,但仅支持在父对象中使用。在使用告示牌时生效。在聊天页面和成书中,将以玩家的身份输入 value并发送。这可以用于执行命令,但需要玩家拥有权限;命令必须拥有“/”前缀,否则将会视为聊天信息。在告示牌中,命令将由服务器在告示牌所在的位置执行,并将使用告示牌的玩家视为执行者。因为命令由服务器执行,告示牌命令无视玩家的权限等级,其与命令方块的权限等级相同;且其不受聊天框长度的限制,可以省略“/”前缀。
- “suggest_command”:打开聊天页面并输入 value。若聊天框已有内容,其将会被覆盖。
- “change_page”:仅在成书中生效。若指定页面存在,将翻至第 value页。
- “copy_to_clipboard”:将 value复制到剪贴板中。
- value:指定的URL、文件路径、信息、命令或页码。
- action:点击时发生的事件。有效值有:
- hoverEvent:可选。允许在玩家将鼠标指针悬浮在文字之上时显示提示文字。
- action:提示文字的类型。有效值有:
- “show_text”:显示原始JSON文本对象。
- “show_item”:显示一个物品的提示文字。与在物品栏中悬浮在物品上时出现的提示文字相同。
- “show_entity”:显示实体的名称、类型和UUID。用于 selector中。
- value:此标签的格式取决于 action的值。不推荐使用,请使用 contents代替。
- “show_text”:另一个JSON文本对象。可以使用字符串、数组或对象。
- “show_item”:包含一个物品的SNBT的字符串。参见player.dat格式#物品结构。
- “show_entity”:包含SNBT的字符串。其不包含所有的实体数据,仅存有实体的名称、类型和UUID。
- name:可选,若未指定则隐藏本参数。指定该实体的名称并显示。包含将被解析为文本对象的JSON文本。若字符串无法被解析为文本对象,整个提示文字将会显示为“无效的实体!”。
- type:可选,若未指定则隐藏本参数。指定该实体的类型。包含将视为实体类型的纯文本,可以为任何文字。
- id:可选,若未指定则显示为空行。指定该实体的UUID。包含将视为UUID的纯文本,可以为任何文字。
- contents:此标签的格式取决于 action的值。
- “show_text”:另一个JSON文本对象。可以使用字符串、数组或对象。
- “show_item”:将要显示的物品。
- id:物品的命名空间物品ID。若无效则视为
minecraft:air
。 - count:可选。物品的数量。
- tag:可选。包含物品的NBT标签。参见player.dat格式#物品结构。
- id:物品的命名空间物品ID。若无效则视为
- “show_entity”:将要显示的实体。
- name:可选,若未指定则隐藏本参数。将显示为实体名称的原始JSON文本对象。
- type:指定实体的类型。应为一个命名空间实体ID。若无效则视为
minecraft:pig
。 - id:指定实体的UUID。应为一个有效的由连字符连接的十六进制UUID。
- action:提示文字的类型。有效值有:
由于extra标签的存在,以上格式可递归嵌套成非常复杂与多样的字符串。然而,JSON文本不必弄得如此复杂:几乎所有的属性都是可选的。
解析组件
部分组件(“score”、“selector”和“nbt”)不会一直存在于对象中。这些内容会被解析:从世界中取得指定数据后将会把数据转化为文本组件,之后用这个转化后的组件替换原来的组件。解析会通过告示牌、第一次打开成书和使用命令完成。它也可以通过战利品表函数“set_name”和“set_lore”完成。在自定义名称中不会自行解析这些组件。
此外,解析会固定获取的值。因此,这些组件的内容不再变化,也不会因环境的变化而调整相应值。
基岩版
与Java版不同,基岩版里的原始JSON文本更为简单且严格。
- 根标签。
- rawtext:包含所有文本对象的列表。
- 基础聊天对象。
- text:在文本中直接出现的原始文本的字符串。存在 translate时忽略。
- selector:在文本中直接将”@a”,”@s”等选择器会被转换。
- translate:使用玩家所选择的语言显示的翻译识别符。此识别符与在assets文件或材质包的lang文件中所发现的识别符相同。
- with:包含 translate使用的聊天字符串参数的列表。在其他情况下没有效果。
- 与当前语言中使用的参数按顺序所对应的文本(例如,列表中的第一个元素对应于translate中的“%%1”)。
- score
- score:在文本中可用显示计分板中的数值。
- name :可使用“@s”,“@a” 等目标选择器或假名,与 selector无关。如果为
*
,则会显示阅读者自己的分数(例如,/tellraw @a {"rawtext":[{"score":{"name":"*","objective":"obj"}}]}
会向每个在线玩家显示他们自己在“obj”记分项的分数)。 - objective :选定要显示分数的 name所在记分项的名称。
- name :可使用“@s”,“@a” 等目标选择器或假名,与 selector无关。如果为
- score:在文本中可用显示计分板中的数值。
- 基础聊天对象。
- rawtext:包含所有文本对象的列表。