实体问题排查指南

0.0.0 - 你搞砸了 ​

先承认某个地方出了问题。_任何人_在任何水平都可能犯这些错误，所以别觉得被冒犯而想着"我当然知道这个！"就跳过步骤！

1.0.0 - 两个包都激活了吗？ ​

确保资源包和行为包都在世界中激活（一个很好的避免方法是：在两个包的manifest.json文件中将彼此设为依赖项，这样添加或移除其中一个包时会自动添加/移除另一个）

2.0.0 - 确定问题是出在RP还是BP ​

通过观察实体生成蛋在创造模式物品栏中的显示情况，可以大幅缩小问题范围。即使你不想要生成蛋，也请暂时进行以下修改以定位问题：

在RP中 ​

确保.entity文件包含如下自定义spawn_egg对象：

"spawn_egg":{
    "base_color": "#FF0000",
    "overlay_color": "#FFFF00"
}

为了本指南，你选择的颜色需要是非"#000000"的值。

在BP中 ​

确保description对象中设置了is_spawnable和is_summonable为true，且is_experimental为false：

"description":{
    "identifier": "wiki:example_entity",
    "is_spawnable": true,
    "is_summonable": true,
    "is_experimental": false
}

结果 ​

完全看不到生成蛋：前往

能看到生成蛋但是纯黑色，且生成/召唤时不显示实体：前往

能看到生成蛋且颜色正确，但生成/召唤时仍不显示实体：前往

3.0.0 - 定位具体问题 ​

3.1.0 - BP问题 ​

在创造模式物品栏中看不到实体生成蛋，即使确认行为文件中"is_spawnable"设为true

这意味着游戏完全没检测到行为文件。常见原因包括：

• 行为文件语法错误
• 文件夹命名错误

3.1.1 - 语法错误 ​

.json文件中单个语法错误会导致整个文件失效。要检查语法，可访问Json Lint，将行为文件内容粘贴到框中，点击"Validate JSON"验证。 （注意：虽然该网站会将//注释标记为错误，但Minecraft允许.json文件包含注释）

3.1.2 - 文件夹命名错误 ​

确保行为包中包含行为文件的文件夹名为"entities"而非"entity"。行为包中通常用"entities"，而资源包中用"entity"。是的，这很不友好。

3.2.0 - RP的.entity文件问题 ​

能看到生成蛋但呈黑色（名称可能显示为"item.spawn_egg.entity.wiki:your_mob.name"这种奇怪格式），且生成/召唤时不显示任何实体

这说明行为文件有效，但游戏未能将其与资源包中的.entity文件关联。常见原因包括：

• .entity文件语法错误
• 实体标识符不匹配
• .entity文件引用的资源无效
• 确认RP文件夹是"entity"，BP文件夹是"entities"

3.2.1 - 语法错误 ​

同上，使用Json Lint验证.entity文件语法。

3.2.2 - 标识符不匹配 ​

行为文件和.entity文件中的"identifier"必须完全相同，包括命名空间（冒号前的部分如minecraft:bat中的minecraft），且除非是默认生物否则不应使用minecraft作为命名空间。

标识符不应包含空格或特殊字符（冒号除外），且为避免罕见bug，建议命名空间和ID都以小写字母开头。虽然以数字或大写字母开头理论上没问题，但早期版本存在相关bug，最好避免。

3.2.3 - 无效资源 ​

.entity文件中实体ID与行为文件使用的ID不匹配。

3.3.0 - RP资源问题（编写中） ​

能看到正确颜色的生成蛋，但生成/召唤时不显示实体或只有阴影

说明.behavior和.entity文件有效，但.entity文件指向了损坏文件或指向了另一个最终指向损坏文件的文件。

根据现象选择：

• 完全隐形无阴影 → RP引用问题：前往
• 隐形但有阴影 → 几何体问题：前往
• 可见但纹理异常 → 贴图问题：前往
• 可见但显示异常 → 材质问题：前往

3.3.1 - 完全隐形无阴影 ​

可能原因包括...首先确认实体确实存在（比如没有设置instant_despawn导致立即消失）。

3.3.2 - 隐形但有阴影 ​

可能由几何体错误或材质错误导致（如果使用半透明/发光纹理时）：

1. 检查几何体名称拼写、文件有效性及偏移量是否正确
2. 确认使用正确的材质类型（某些材质仅支持发光纹理）
3. 检查渲染控制器是否存在问题

3.3.3 - 可见但纹理异常 ​

3.3.4 - 可见但显示异常 ​