SNBT格式

SNBT是一种用文本表示的树状数据结构。

概述

SNBT将游戏中的数据结构转换为适合阅读的文本，以供玩家检索和操纵。其常用于获取和修改数据的各种命令中。客户端核心文件中的数据生成器也可以以SNBT形式输出数据。

SNBT也可以看作是NBT的一种文本表示，但二者格式并不完全一致。

结构

SNBT是由若干字符构成的文本。SNBT的数据类型可以大致分为数值、字符串、结构型数据，其中，一个结构型数据可以包含多个数据，且能相互嵌套以组织数据为树状结构。SNBT的基本符号构成如下：

结构化符号

• [、]：线性表开始和结束符。
• {、}：复合数据结构的开始和结束符。
• ,：键值对分隔符。
• "、'：字符串开始或结束符
• \：字符串内的字符转义符。

数值

数值表示单个数字、文本或真值。

布尔值

• true
• false

布尔值表示一个真值，可以为真或假。

这一真值用不区分大小写的字面量表示：true表示真，false表示假。

整数字面量

• 123
• 0xABC
• 0b00000000ub

整数字面量根据数据范围不同分为若干类型，且根据是否支持负数有无符号与有符号两种变种^{[新增：JE 1.21.5]}。整数值按十进制、二进制或十六进制^{[新增：JE 1.21.5]}表示。

整数字面量的格式为<某进制的整数值><整数类型后缀>。其中，<某进制的整数值>可以表示为<十进制数>、0b<二进制数>或0x<十六进制数>。十进制表示法的数字不能以0开头，但允许单个0。数位中间可以插入下划线_以分割数位^{[新增：JE 1.21.5]}。<整数类型后缀>为一串不区分大小写的特定字符，表示整数字面量的类型，具体如下表所示。

图标和类型名称	整数类型后缀	数据范围
字节型	b（十进制）、 sb[新增：JE 1.21.5]	-128 – 127
	b（非十进制）、ub[新增：JE 1.21.5]	0 – 255
短整型	s（十进制）、 ss[新增：JE 1.21.5]	-32768 – 32767
	s（非十进制）、us[新增：JE 1.21.5]	0 – 65535
整型	i（十进制）、 si[新增：JE 1.21.5]	-2147483648 – 2147483647
	i（非十进制）、ui[新增：JE 1.21.5]	0 – 4294967295
长整型	l（十进制）、 sl[新增：JE 1.21.5]	-9223372036854775808 – 9223372036854775807
	l（非十进制）、ul[新增：JE 1.21.5]	0 – 18446744073719551615

无类型后缀时，游戏会自动推断其类型。 如该整数字面量在数组中作为元素时，其类型为该数组所标定的整数类型；否则，^{[新增：JE 1.21.5]}其类型推定为整型。

由于类型后缀与十六进制数格式冲突，十六进制的字节型整数字面量必须使用sb或ub后缀。^{[新增：JE 1.21.5]}

浮点数字面量

• 1.2
• 3e12d

浮点数字面量表示一个一定范围内的小数。浮点数根据数据范围不同分为单精度与双精度两种类型，均符合IEEE754标准。浮点数数值只能以十进制表示，不支持IEEE754标准中的十六进制表示法。

浮点型字面量的格式为<浮点数数值><浮点数类型后缀>。其中，<浮点数数值>可以是一个整数，或者带小数点的小数，或者形如<尾数>e<指数>或<尾数>E<指数>的科学计数法表示。小数的整数部分和小数部分之一可以省略，但不能均省略。数位中间可以插入下划线_，以分割数位。^{[新增：JE 1.21.5]}<浮点数数值>为一串不区分大小写的特定字符，表示浮点数的类型，具体如下表所示。

图标和类型名称	浮点数类型后缀	数据范围
单精度浮点型	f	-3.4×1038 – 3.4×1038
双精度浮点型	d	-1.7×10308 – 1.7×10308

无类型后缀时，游戏会自动推断其类型。当<浮点数数值>以整数表示时，其类型优先推断为整数值而非浮点数数值；其余情况下，其类型推断为双精度浮点数数值。符合浮点数语法，但因超出数据范围而将被转换为无穷数的值不被接受。^{[新增：JE 1.21.5]}

字符串

• "Hello \u00a7c Minecraft Wiki"
• TestContent

字符串是由一列Unicode字符构成的文本。

字符串有三种格式，分别为<字符序列>（无引号）、'<字符序列>'（单引号）和"<字符序列>"（双引号）。三种格式可以表示相同的字符串内容，但对字符串的表示有限制：未被引号包裹的字符串只能包含数字、字母、小数点、下划线、正负号，不能以+、-、0到9开头^{[新增：JE 1.21.5]}；单引号包裹的字符串不能包含单引号，双引号包裹的字符串不能包含双引号，但这两种引号可以通过下文的转义序列被表示为相应的字符串内容。

字符序列内的字符有下列书写方式：

• 直接写入。
• \x<二位十六进制>、\u<四位十六进制>或\U<八位十六进制>。^{[新增：JE 1.21.5]}
  • 将后跟的十六进制数解析为Unicode码位，表示相应的Unicode字符。前导零不能忽略。
• \N{<名称>}。^{[新增：JE 1.21.5]}
  • 按Unicode字符名称检索Unicode字符。名称只接受大小写字母、数字、空格和-。实际采用Character.codePointOf方法，其对字符名称的解析不完全符合Unicode字符名称规范。
• \<标识符>。
  • 固定的特殊转义序列，接受\\、\'、\"、\r、​\n、​\b、​\s、​\t和\f^{[新增：JE 1.21.5]}。

true和false会优先推断为布尔值而非字符串。

结构标签

结构标签以不同的组织方式承载其他标签，以构成复杂的树状结构。结构标签可以相互嵌套，但嵌套层数不能超过512层。

列表

• []（空列表）
• [1, 2, 3]
• [1, 2, 3, <...>]（元素内容过多时将剩余元素省略）

列表标签表示一列类型不定的无名标签的有序集合。列表中的子标签类型必须相同。^{[失效：JE 1.21.5]}

列表标签的格式为[<子标签>,...]。子标签序列的末尾可以附带单个逗号。^{[新增：JE 1.21.5]}

数组

• [L;]（空长整型数组）
• [I; 1, 2, 3]

数组表示一列特定类型整型的无名标签的有序集合，根据其子标签的类型不同分为若干类型。

数组标签的格式为[<类型标识符>;<子标签>,...]。<类型标识符>为区分大小写的预设标识符；B、I、L分别表示字节型数组、整型数组和长整型数组。子标签必须为给定类型标签、比给定类型范围更小的整型标签或未标明类型的整型标签；后两者会自动转化到给定类型。上述匹配忽略标签是否有符号。子标签序列的末尾可以附带单个逗号。^{[新增：JE 1.21.5]}

复合标签

• {}（空复合标签）
• {tag1:"hello minecraft wiki", tag2:2.0d, tag3:[]}

复合标签表示一列有名标签的集合。这些标签的类型未必相同。

复合标签的格式为{<子标签名>:<子标签>,...}。<子标签名>为符合字符串标签格式的字符串。子标签序列的末尾可以附带单个逗号。^{[新增：JE 1.21.5]}

表达式

表达式不直接表示标签，而是用于调用游戏内置功能，以将参数转换为特定的标签。

表达式的格式为<表达式名>(<参数>,...)。<表达式名>符合无引号字符串的语法。<参数>为要传入表达式的SNBT标签。参数列表末尾允许附加单个逗号。

调用的内置功能由<表达式名>和参数数量共同决定。游戏支持的表达式如下：

内置表达式表

表达式名	参数数量	输出类型	行为
bool	1	布尔型	接受布尔型、整型和浮点型，将输入标签转换为布尔型。如输入布尔型则原样输出；如输入整型或浮点型，则当且仅当输入数值为0时输出false，否则均输出true。
uuid	1	整型数组（四元）	接受字符串，将字符串按照带连字符的十六进制表示转换为UUID。

转换

游戏并不会直接存储SNBT。最终，SNBT需要被转换为程序对象，但这一步并非直接完成，而是以NBT作为中介。这些内容在NBT格式的页面有所介绍。

历史

Java版
?							加入了SNBT格式。
1.12			?				加入了长整型数组标签。
1.14			19w08a				除"外，字符串标签现在可以写在'之间。
Java版（即将到来）
1.21.5			25w04a				加入了异型列表。
			25w09a				整型现在可以指定有符号和无符号。
							整型现在可以以二进制或十六进制书写。
							浮点型现在可以使用科学计数法书写，且小数点前后的数段之一现在可以略去。
							整型和浮点型的各段数位中间现在可以插入下划线。
							列表、数组和复合标签的元素列表末尾现在可以附带单个逗号。
							字符串现在支持更多转义格式，包括Unicode码位转义、Unicode字符名称转义，以及更多特殊控制符转义。
							现在所有组件[需要更多信息]都支持异型列表了。
			25w10a				加入了表达式语法，以及两个内置表达式bool和uuid。
							符合浮点数语法，但因超出数据范围而将被转换为无穷数的值现在不被接受。