doc: update document

- add hint for gray virtools import export button
- add outcome of leaving blank ballance texture folder setting.
- update compile chapter according to the change of build scripts.

.gitattributes

@@ -3,4 +3,4 @@
 # Element placeholder mesh should be save as binary
 *.ph binary
 # Raw json data should be binary, although i edit it manually
-assets/jsons/*.json    binary
+assets/jsons/*.json5    binary

docs/docs/zh-cn/compile-distribute-plugin.md

@@ -12,11 +12,29 @@ BBP的Virtools文件原生导入导出功能依赖BMap以及其Python绑定PyBMa
 
 然后我们需要将配置好的PyBMap拷贝到本项目的根目录下即可完成此步（即存在`bbp_ng/PyBMap`文件夹，为配置好的PyBMap）。
 
-## 生成缩略图和压缩JSON
+## 生成资源
 
-BBP内置了一系列自定义图标，以及其组件BME需要的用于描述结构的JSON文件。通过批量生成缩略图和压缩JSON的操作，可以减小这些部分的大小，使得其适合在Blender中加载，也更方便分发。
+BBP的正常运行离不开一系列资源文件，而这些资源文件则需要一些处理才能够正常使用。
 
-转到`bbp_ng/tools`文件夹下，运行`python3 build_icons.py`将批量生成缩略图（此功能需要PIL库，请提前通过pip安装）。其实际上是将`bbp_ng/raw_icons`目录下的原始图片生成对应的缩略图并存储于`bbp_ng/icons`文件夹下。运行`python3 build_jsons.py`将压缩JSON。其实际上是将`bbp_ng/raw_jsons`目录下的原始JSON文件读取，压缩，再写入到`bbp_ng/jsons`文件夹下。
+为了生成这些资源文件，首先需要转到`scripts`文件夹下，执行`uv sync`指令来还原脚本环境（需提前安装Astral UV）。
+
+### 生成缩略图
+
+BBP内置了一系列自定义图标，但这些图标都以其原始大小存储在库中。通过批量生成缩略图的操作，可以减小这些部分的大小，使得其适合在Blender中加载，也更方便分发。
+
+执行`uv run build_icons.py`来生成缩略图。其实际上是将`assets/icons`目录下的原始图片生成对应的缩略图并存储于`bbp_ng/icons`文件夹下。
+
+### 生成JSON文件
+
+BBP中的BME组件依赖一系列JSON文件来描述原型。这些描述文件以JSON5格式存储在库中，方便编写者阅读。通过批量生成操作，将这些JSON5文件转换为JSON文件并压缩其大小，可以方便其在Blender中加载，以及方便插件分发。
+
+如果你是插件开发者，或者是这些原型的编写者，那么你在生成JSON文件前，还需要额外地进行一项操作：验证JSON文件的正确性。BBP插件在加载这些JSON文件时会默认这些文件都是正确的，无错误的。如果将有错误的JSON文件放入（例如缺少部分字段或者拼写错误等），则会导致Blender在创建原型时抛出错误。所以验证JSON文件的正确性很有必要。执行`uv run validate_jsons.py`来验证所有原型文件。如果没有任何报错，则验证无误。需要注意的是，验证器并非完美的，它只能尽可能地验证数据，确保一些常见的错误，例如字段名称拼写错误等，不会发生，并不能100%保证验证后的文件没有错误。
+
+对于编译人员而言，只需要执行`uv run build_jsons.py`来生成JSON文件即可。其实际上是将`assets/jsons`目录下的原始JSON5文件读取，压缩，再以JSON格式写入到`bbp_ng/jsons`文件夹下。
+
+### 生成机关网格
+
+BBP中内置了Ballance所有机关占位符的网格信息。执行`uv run build_meshes.py`来部署这些内容，其简单地将`assets/meshes`下的网格文件复制到`bbp_ng/meshes`文件夹下。
 
 ## 翻译
 
@@ -31,7 +49,7 @@ Blender对于插件的多语言支持不尽如人意，且BBP的设计比较特
 
 ### 提取翻译模板
 
-在翻译之前，首先你需要意识到，BBP需要翻译的文本由两部分组成，一部分是BBP插件本身，可以通过Blender自带的多语言插件来实现待翻译文本的提取。另一部分是BME组件中的用于描述结构的JSON文件，其中各个展示用字段的名称需要进行翻译，而这一部分Blender的多语言插件无能为力，因为它是动态加载的。幸运的是，我们已经写好了一个提取器，可以提取BME的JSON文件中的相关待翻译文本，当你在进行上一步压缩JSON的操作时，实际上压缩器也一并运行了，并提取了待翻译文本写入了`bbp_ng/i18n/bme.pot`文件中。那么接下来的任务就只剩下提取插件部分的翻译了。
+在翻译之前，首先你需要意识到，BBP需要翻译的文本由两部分组成，一部分是BBP插件本身，可以通过Blender自带的多语言插件来实现待翻译文本的提取。另一部分是BME组件中的用于描述结构的JSON文件，其中各个展示用字段的名称需要进行翻译，而这一部分Blender的多语言插件无能为力，因为它是动态加载的。幸运的是，我们已经写好了一个提取器，可以提取BME的JSON文件中的相关待翻译文本。就是在上一步运行脚本的文件夹中，执行`uv run extract_jsons.py`，脚本就会提取待翻译文本并写入`i18n/bme.pot`文件中。那么接下来的任务就只剩下提取插件部分的翻译了。
 
 首先你需要启用Blender内置的多语言插件Manage UI translations。为了启用它，你可能还需要下载对应Blender版本的源代码和翻译仓库，具体操作方法可参考[Blender的官方文档](https://developer.blender.org/docs/handbook/translating/translator_guide/)。在启用插件并在偏好设置中配置了合适的相关路径后，你就可以在Render面板下找到I18n Update Translation面板，接下来就可以提取翻译了。按照以下步骤提取翻译：
 
@@ -41,11 +59,11 @@ Blender对于插件的多语言支持不尽如人意，且BBP的设计比较特
     * Simplified Chinese (简体中文)
 1. 点击最下方一栏的Refresh I18n Data按钮，然后在弹出的窗口中选择Ballance Blender Plugin，等待一会后，插件就会完成待翻译字符的提取。此时插件只是将他们按照Blender推荐的方式，以Python源码的格式将翻译字段提取到了插件的源代码中。
 1. 为了获得我们希望的，可以用于编辑的POT文件，还需要点击Export PO按钮，在弹出的窗口中选择Ballance Blender Plugin，保存的位置可以选择任意的文件夹（例如桌面，因为它会产生许多文件，其中只有POT文件才是我们想要的），取消勾选右侧的Update Existing选项并确保Export POT是勾选的，最后进行保存。导出完成后，可以在你选择的文件夹中找到一个名为`blender.pot`的翻译模板文件，以及众多以语言标识符为文件名的`.po`文件。
-1. 你需要复制`blender.pot`到`bbp_ng/i18n`文件夹下，并将其重命名为`bbp_ng.pot`。至此我们提取了所有需要翻译的内容。
+1. 你需要复制`blender.pot`到`i18n`文件夹下，并将其重命名为`bbp_ng.pot`。至此我们提取了所有需要翻译的内容。
 
 ### 合并翻译模板
 
-现在`bbp_ng/i18n`文件夹下有两个POT文件，分别代表了两部分提取的待翻译文本，我们需要把他们合并起来。在`bbp_ng/i18n`文件夹执行`xgettext -o blender.pot bbp_ng.pot bme.pot`来进行合并。合并完成后的`bbp_ng/i18n/blender.pot`将用作翻译模板。
+现在`i18n`文件夹下有两个POT文件，分别代表了两部分提取的待翻译文本，我们需要把他们合并起来。在`i18n`文件夹执行`xgettext -o blender.pot bbp_ng.pot bme.pot`来进行合并。合并完成后的`i18n/blender.pot`将用作翻译模板。
 
 ### 创建新语言翻译
 
@@ -80,7 +98,7 @@ PO格式的翻译并不能被Blender识别，因此在翻译完成后，你还
 1. 首先确保关闭了所有Blender进程，否则插件会保持在加载状态，对翻译元组变量的修改会不起作用。
 1. 将插件中翻译元组变量`translations_tuple`的值改为空元组（参见前文有关提交的注意事项）。这一步操作的意图是让整个插件不存在翻译条目，这样之后在使用Import PO功能的时候，Blender的多语言插件就会认为PO文件中存储的所有字段都是要翻译的，就不会出现只导入了一部分翻译的情况（因为BME部分的翻译是后来合并入的）。
 1. 打开Blender，转到I18n Update Translation面板，按照提取翻译模板时的操作方法，在语言列表中仅选中需要翻译的语言。
-1. 点击最下方一栏的Import PO按钮，然后在弹出的窗口中选择Ballance Blender Plugin，然后选择`bbp_ng/i18n`文件夹进行导入。这样我们就完成了将PO文件导入为Blender可识别的Python源码格式的操作。
+1. 点击最下方一栏的Import PO按钮，然后在弹出的窗口中选择Ballance Blender Plugin，然后选择`i18n`文件夹进行导入。这样我们就完成了将PO文件导入为Blender可识别的Python源码格式的操作。
 
 ## 打包
 

docs/docs/zh-cn/configure-plugin.md

@@ -19,7 +19,9 @@ BBP插件目前有2个设置需要配置。
 
 请填写为Ballance的`Texture`目录，插件将从此目录下调用外置贴图文件（即Ballance原本带有的贴图文件）。点击右侧的文件夹按钮可以浏览文件夹并选择。
 
-这是关乎BBP是否正常运行的关键，只有填写正确，BBP才不会在运行中出错。
+该选项几乎是必填写的。如果不填写该项目，则Virtools文件导入导出，BME创建，钢轨创建等各种核心功能将不可用（按钮为灰色）。
+
+该选项是BBP能否正常运行的关键，只有填写正确，BBP才不会在运行中出错。
 
 ### No Component Collection
 

docs/docs/zh-cn/import-export-virtools.md

@@ -56,3 +56,11 @@ Ballance Params（Ballance参数）章节包含针对Ballance特有内容，对
 Successive Sector（小节连续）是一个解决导出小节组时出现的Bug的选项。由于某些原因，如果一个小节中没有任何机关（实际上是某小节组中没有归入任何物体），导出插件会认为该小节组不存在，因而遗漏导出。且由于Ballance对最终小节，即飞船出现小节的判定是从1开始递增寻找最后一个存在的小节组，所以二者叠加，会导致Ballance错误地认定地图的小节数，从而在错误的小节显示飞船，这也就是导出Bug。当勾选此选项后，导出文档时会预先按照当前Blender文件中Ballance地图信息中指定的小节数预先创建所有小节组，然后再进行导出，这样就不会遗漏创建某些小节组，飞船也会在正确的小节显示。
 
 这个选项通常在导出可游玩的地图时选中，如果你只是想导出一些模型，那么需要关闭此选项，否则会在最终文件中产生许多无用的小节组。
+
+## 无法导入导出
+
+通常而言，在你正确按照之前介绍的步骤安装和配置插件后，你理论上就可以使用Virtools文档的导入导出功能了。但难免有意外发生。这里说的无法导入导出指的是导入和导出Virtools文档的按钮是灰色的，不可点击的。你需要按照下述步骤检查。如果你所指的是在导入导出过程中出错了，请参考本页页首的警告信息。
+
+首先检查你是否已经在[配置插件](configure-plugin.md)章节正确配置了插件的`External Texture Folder`设置项。如果你没有配置，则自然无法导入导出Virtools文件。因为导入导出Virtools文件需要依赖Ballance原版关卡数据。请按教程认真配置这一设置项。
+
+如果你确定你已经设置了正确的贴图路径，你可以尝试点击菜单`Window - Toggle System Console`来打开控制台。在控制台中，可能会有一些相关的错误信息输出在其中，例如加载底层BMap库时失败等。加载底层BMap库失败通常只发生在一些罕见架构的机器上，例如使用Snapdragon处理器的Windows系统等，因为我们打包的插件中，并未包含支持这些平台的Virtools文件底层读取库BMap。在面对这种情况时，你有两个选择，一是汇报给开发者，等待开发者主动支持，二是自行编译该库（仅建议有丰富计算机知识的人这样做）。