命名空间¶

命名空间（Namespace）是赋命名空间标识符中用于区分内容来源的名称前缀。命名空间通过在标识符中划分来源范围，避免不同附加包、原版内容或工具生成内容之间发生名称冲突。

概述¶

在Minecraft基岩版中，大量游戏对象使用赋命名空间标识符表示，例如minecraft:zombie、minecraft:stone和example:custom_block。冒号前的部分即命名空间，冒号后的部分是在该命名空间内的名称。

命名空间的存在使不同来源可以使用相同的本地名称而不互相覆盖。例如，两个附加包都可以定义名为chair的内容，只要它们分别使用不同命名空间，如studio_a:chair和studio_b:chair，游戏就能将二者区分开。

原版游戏内容通常使用minecraft命名空间。该命名空间由游戏自身保留，用于实体、方块、物品、组件、状态、粒子、声音事件等原版对象。

附加包开发者不应将自定义内容放入minecraft命名空间，也不应使用minecon等可能被官方或历史内容占用的命名空间。使用保留或高度通用的命名空间会增加与原版更新、其他附加包或平台内容发生冲突的风险。

自定义命名空间通常用于标识作者、团队、项目或作品系列。理想的命名空间应具有以下特征：

命名空间一旦公开发布后不宜随意更改。更改命名空间会改变所有相关标识符，可能导致旧存档中的方块、物品、实体或引用失效。

命名空间不仅用于自定义实体、方块和物品，也用于动画、动画控制器、粒子特效、渲染控制器、声音事件、结构、地物等多种内容。命名空间还常用于资源短名称和内部引用，以保持包内资源的组织一致。

在大型附加包中，统一命名空间有助于形成稳定的资源边界。多个配套包共享同一项目命名空间时，应确保内部命名规则一致，避免同项目不同模块之间发生重复定义。

命名空间和文件路径有关，但并不总是等同。某些内容会在JSON字段中显式声明赋命名空间标识符，某些内容则主要通过文件路径定位。例如函数使用functions/目录下的文件路径调用，而不是使用命名空间:路径形式。开发时应以对应格式的规则为准，不能简单假设文件夹名称必然就是命名空间。