命名空间ID

命名空间ID（Namespaced identifier，或译为（赋）命名空间标识符）、资源路径（Resource location）、资源标识符（Resource identifier）或命名空间字符串（Namespaced string）是用来指明和识别游戏中特定对象而又能避免潜在的歧义和冲突的一种方式。

定义

Java版1.21.11前，命名空间ID在游戏内部为资源路径（Resource location），主要由以下两部分组成：

• 命名空间（Namespace）：一个字符串，用于标识资源的唯一性。游戏的默认命名空间为minecraft，另外Realms也使用单独的命名空间realms。
• 路径（Path）：一个字符串。在数据包中，一般也反应了该资源的文件路径。有时也仅作为一种标识名。

在转换为字符串形式时，命名空间和路径之间使用:作为分隔符。关于命名空间ID的合法字符以及转换方式，可参见后文。

介绍

命名空间ID可使用纯文本字符串表示，用以引用游戏中的方块、物品、实体类型、配方、函数、进度、标签等对象。特别地，方块状态不使用命名空间ID。

有效的命名空间ID字符串格式为<命名空间>:<名称>，其中只能使用合法字符。

合法字符

Java版

命名空间和名称只能包含以下字符：

• 0123456789 数字
• abcdefghijklmnopqrstuvwxyz 小写字母
• _ 下划线
• - 连字符号
• . 英文句号

以下字符在命名空间中是非法的，但在名称中可以接受：

• / 斜杠
  • 用于划分目录。

命名空间和名称的最好命名方法是小写单词加下划线（snake_case）。

基岩版

ID的命名空间和名称可以包含任何符号，斜杠“/”和冒号“:”除外。

以下字符在命名空间中是非法的，但在战利品表和函数的名称中是可接受的。

• / 斜杠
  • 用于划分目录。

命名空间和名称的最好命名方法是小写单词加下划线（snake_case）。

命名空间ID转换为字符串

在生成NBT对象时，若读取到的实体/方块的属性值为命名空间ID类型^{[需要验证]}，则必须转换为符合NBT格式规范的字符串类型。

将命名空间和名称使用:进行连接，即可得到字符串形式的命名空间ID。

例子：

命名空间	名称	字符串表示
minecraft	diamond	minecraft:diamond
foo	bar.baz	foo:bar.baz
foo	bar/baz	foo:bar/baz

字符串转换为命名空间ID

命名空间ID总能顺利转换为字符串，而从字符串转换为命名空间ID需要满足一些限制条件，否则转换失败。

限制条件：

• 字符串最多只能有一个:（冒号）。
• 字符串的命名空间和名称部分必须符合合法字符的限制。
• 如果有:，:前面不能有/或.。

若存在:，其前半部分将作为命名空间，后半部分为名称。

在Java版或基岩版的某些地方，若不存在:，minecraft将被作为命名空间，整个转换前的字符串则是名称。

例子：

字符串	识别的命名空间	识别的名称	游戏再输出为字符串
bar:code	bar	code	bar:code
minecraft:zombie	minecraft	zombie	minecraft:zombie
diamond	minecraft[仅Java版] 无[仅基岩版]	diamond	minecraft:diamond[仅Java版] diamond[仅基岩版]
foo/bar:coal	无效字符/
minecraft/villager	minecraft[仅Java版] 无[仅基岩版]	minecraft/villager	minecraft:minecraft/villager[仅Java版] minecraft/villager[仅基岩版]
mypack_recipe	minecraft[仅Java版] 无[仅基岩版]	mypack_recipe	minecraft:mypack_recipe[仅Java版] mypack_recipe[仅基岩版]
mymap:schrödingers_var	mymap	无效字符ö[仅Java版] schrödingers_var[仅基岩版]	mymap:schrödingers_var[仅基岩版]
custom_pack:Capital	custom_pack	无效字符C[仅Java版] Capital[仅基岩版]	custom_pack:Capital[仅基岩版]

使用

以下对象可以使用命名空间ID：

Java版

在Java版中，命名空间ID在注册表中主要作为对象的主键，或者包中文件的路径。另外，一些自定义或硬编码内容也使用命名空间ID。

游戏内置：

• 属性
• 方块
• 方块实体
• 液体
• 游戏事件
• 物品
• 数据组件谓词
• 物品堆叠组件
• 实体种类
• 生物记忆
• 村民职业
• 村民类型
• 状态效果
• 药水效果
• 粒子类型
• 统计信息
• 配方类型
• 配方序列化器
• 命令参数类型
• 战利品表类型
• 声音事件

包内容

数据包内容

• 进度
• 战利品表
• 谓词
• 物品修饰器
• 函数
• 结构
• 配方
• 标签
• 生物群系
• 伤害类型
• 维度
• 魔咒
• 画的变种
• 狼的变种

资源包内容

• 方块状态文件
• 模型
• 纹理
• 声音

其他可修改的

• Boss栏
• 命令存储
• 属性修饰符

基岩版

游戏内置：

• 原版的方块、物品、实体、状态效果、维度、生物群系、地物等
• 命令的物品组件
• 附加包文件中方块、实体等使用的组件
• 附加包的JSON模式
• GameTest脚本启用的组件

附加包内容

行为包内容

• 方块
• 实体
• 物品
• 生物生成规则
• 生物群系
• 地物
• 地物规则
• 功能域
• 配方
• 结构
• GameTest
• NPC对话场景

资源包内容

• 附着物
• 相机视角
• 粒子效果
• 迷雾设置

实际文件路径

命名空间ID指定的对象可能是资源包和数据包里的文件。

通常，资源包和数据包中文件的路径是<包类型>/<命名空间>/<对象类型>/<名称>.<后缀名>，就有相应的形如 <命名空间>:<名称> 的命名空间ID。所有的/（可能在<对象类型>或<名称>中）都是用来划分文件目录的。

对象的类型与<包类型>、<对象类型>和<后缀名>变量的相互转换

对象的类型	包的类型	包类型的值	对象类型的值	后缀名的值
方块状态映射	资源包	assets	blockstates	json
模型			models	json
粒子			particles	json
纹理			textures	png
进度	数据包	data	advancement	json
函数			function	mcfunction
战利品表			loot_table	json
配方			recipe	json
结构			structure	nbt
方块标签			tags/block	json
实体类型标签			tags/entity_type	json
物品标签			tags/item	json
流体标签			tags/fluid	json
函数标签			tags/function	json

注意：资源包中的某些元素不一定依靠具有命名空间ID的对象（如GUI纹理）。

在知道实际文件路径后，就可以通过它知道命名空间ID。同样的，在知道命名空间ID指定的对象的类型后，就可以通过它找到实际文件路径。

一些例子

命名空间ID	对象的类型	包类型	对象类型	后缀名	文件路径
my_texture_pack:diamonds	纹理	assets	textures	png	assets/my_texture_pack/textures/diamonds.png
abc:run_game	函数	data	function	mcfunction	data/abc/function/run_game.mcfunction
block/torch （相当于minecraft:block/torch）	模型	assets	models	json	assets/minecraft/models/block/torch.json
load （相当于 minecraft:load）	函数标签	data	tags/function	json	data/minecraft/tags/function/load.json
rocket_pack:industry/start_of_story	进度	data	advancement	json	data/rocket_pack/advancement/industry/start_of_story.json

命名空间

“

这不是一个新概念，但是我想我应重申一下什么是“命名空间”。游戏中的大多数东西都有一个命名空间，以便在我们加入了something的同时一个mod（或地图，或其他）也加入了something时来区分它们两个。当你要为某个东西命名时，例如一个战利品表，你还需要指定这个东西所属的命名空间。如果你不指定命名空间，我们默认它是minecraft。这意味着something和minecraft:something是一回事。

”

——Dinnerbone评论于命名空间

命名空间起到了对资源的隔离作用。它可防止潜在的内容冲突或无意中覆盖了相同名称的对象。

例如，通过修改zombie.json战利品表来改变僵尸的战利品：假设此时没有命名空间存在，那么所有资源都将直接存储于数据包根目录下。此时管理与原版有差异的资源将相当困难——若新增一个zombie.json僵尸战利品表，则必定会完全覆盖掉原版数据包中的僵尸战利品表。使用命名空间，可以有效增加一个不同的zombie.json僵尸战利品表，且数据包作者和游戏都能够很轻松地识别。例如，原版僵尸战利品表位于minecraft命名空间内，而新增的僵尸战利品表位于my_test命名空间内，则这两个僵尸战利品表将被明确地识别为minecraft:zombie和my_test:zombie。

minecraft命名空间

游戏本身使用minecraft命名空间。在Java版中，当没有指定命名空间时，将默认为minecraft。只有当项目需要覆盖或修改现有的“minecraft”数据或将内容加入到原版标签时，才应该使用minecraft命名空间。比如在minecraft:load函数标签中加入函数。

自定义命名空间

不同的项目或内容创作（例如数据包、资源包、mod等），命名空间应该是不同的。仅当需要覆盖其他项目，或是追加标签的时候，才使用与其他项目相同的命名空间。

为了防止潜在的冲突，命名空间应该尽可能的特殊。

• 避免使用一堆字母的组合。例如，一个名为“nuclear craft”的项目不应该使用命名空间nc，因为太简单了。
• 避免使用过于模糊的词语。battle_royale也不能提供便于查找的信息，不过player_name_battle_royale会更好些。

这些不当的命名空间都会减少项目的适应程度，并在将多个项目加入到游戏时给调试带来困难。

其他内置的命名空间

虽然本地化键名并不使用命名空间ID，但游戏的默认资源包声明了realms命名空间来储存面向Realms的语言文件（位于assets/realms/lang/<语言代码>.json），而minecraft命名空间储存与游戏相关的语言文件。Realm的jar文件本身也在realms命名空间中声明了它的en_us.json语言文件及各种纹理。

在命令参数类型中，还有一个brigadier命名空间存在于brigadier中。

历史

Java版
1.6.1			13w21a				加入了命名空间ID和minecraft前缀。
1.7.2			13w37a				命令现在在接受数字ID的同时也可以接受名称ID了。
1.8			14w03b				命令现在不再接受数字ID。
1.11			16w32a				命名空间ID有了一个字符限制。
							命名空间ID中不允许使用大写字母。
1.13			17w47a				在扁平化之后，命名空间ID是唯一可接受的ID形式，不再接受数字ID。
			pre4				命名空间ID现在用于标识插件消息通道。
1.14.4			pre1				在Client.jar的内置资源包中加入了命名空间realms。
1.16			20w14a				属性现在是命名空间化的ID。
携带版Alpha
0.16.0			build 1				加入了命令，支持字符串ID，但这些ID没有命名空间。
基岩版
1.12.0			1.12.0.2				加入了命名空间ID和minecraft前缀，以支持通过附加包加入自定义物品。

参见

• Java版数据值
• 资源包
• 数据包

外部链接

• 命名空间的解释Minecraft Snapshot 17w43a — minecraft.net。。