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.
This commit is contained in:
2
.gitattributes
vendored
2
.gitattributes
vendored
@ -3,4 +3,4 @@
|
|||||||
# Element placeholder mesh should be save as binary
|
# Element placeholder mesh should be save as binary
|
||||||
*.ph binary
|
*.ph binary
|
||||||
# Raw json data should be binary, although i edit it manually
|
# Raw json data should be binary, although i edit it manually
|
||||||
assets/jsons/*.json binary
|
assets/jsons/*.json5 binary
|
||||||
|
@ -12,11 +12,29 @@ BBP的Virtools文件原生导入导出功能依赖BMap以及其Python绑定PyBMa
|
|||||||
|
|
||||||
然后我们需要将配置好的PyBMap拷贝到本项目的根目录下即可完成此步(即存在`bbp_ng/PyBMap`文件夹,为配置好的PyBMap)。
|
然后我们需要将配置好的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面板,接下来就可以提取翻译了。按照以下步骤提取翻译:
|
首先你需要启用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 (简体中文)
|
* Simplified Chinese (简体中文)
|
||||||
1. 点击最下方一栏的Refresh I18n Data按钮,然后在弹出的窗口中选择Ballance Blender Plugin,等待一会后,插件就会完成待翻译字符的提取。此时插件只是将他们按照Blender推荐的方式,以Python源码的格式将翻译字段提取到了插件的源代码中。
|
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. 为了获得我们希望的,可以用于编辑的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. 首先确保关闭了所有Blender进程,否则插件会保持在加载状态,对翻译元组变量的修改会不起作用。
|
||||||
1. 将插件中翻译元组变量`translations_tuple`的值改为空元组(参见前文有关提交的注意事项)。这一步操作的意图是让整个插件不存在翻译条目,这样之后在使用Import PO功能的时候,Blender的多语言插件就会认为PO文件中存储的所有字段都是要翻译的,就不会出现只导入了一部分翻译的情况(因为BME部分的翻译是后来合并入的)。
|
1. 将插件中翻译元组变量`translations_tuple`的值改为空元组(参见前文有关提交的注意事项)。这一步操作的意图是让整个插件不存在翻译条目,这样之后在使用Import PO功能的时候,Blender的多语言插件就会认为PO文件中存储的所有字段都是要翻译的,就不会出现只导入了一部分翻译的情况(因为BME部分的翻译是后来合并入的)。
|
||||||
1. 打开Blender,转到I18n Update Translation面板,按照提取翻译模板时的操作方法,在语言列表中仅选中需要翻译的语言。
|
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源码格式的操作。
|
||||||
|
|
||||||
## 打包
|
## 打包
|
||||||
|
|
||||||
|
@ -19,7 +19,9 @@ BBP插件目前有2个设置需要配置。
|
|||||||
|
|
||||||
请填写为Ballance的`Texture`目录,插件将从此目录下调用外置贴图文件(即Ballance原本带有的贴图文件)。点击右侧的文件夹按钮可以浏览文件夹并选择。
|
请填写为Ballance的`Texture`目录,插件将从此目录下调用外置贴图文件(即Ballance原本带有的贴图文件)。点击右侧的文件夹按钮可以浏览文件夹并选择。
|
||||||
|
|
||||||
这是关乎BBP是否正常运行的关键,只有填写正确,BBP才不会在运行中出错。
|
该选项几乎是必填写的。如果不填写该项目,则Virtools文件导入导出,BME创建,钢轨创建等各种核心功能将不可用(按钮为灰色)。
|
||||||
|
|
||||||
|
该选项是BBP能否正常运行的关键,只有填写正确,BBP才不会在运行中出错。
|
||||||
|
|
||||||
### No Component Collection
|
### No Component Collection
|
||||||
|
|
||||||
|
@ -56,3 +56,11 @@ Ballance Params(Ballance参数)章节包含针对Ballance特有内容,对
|
|||||||
Successive Sector(小节连续)是一个解决导出小节组时出现的Bug的选项。由于某些原因,如果一个小节中没有任何机关(实际上是某小节组中没有归入任何物体),导出插件会认为该小节组不存在,因而遗漏导出。且由于Ballance对最终小节,即飞船出现小节的判定是从1开始递增寻找最后一个存在的小节组,所以二者叠加,会导致Ballance错误地认定地图的小节数,从而在错误的小节显示飞船,这也就是导出Bug。当勾选此选项后,导出文档时会预先按照当前Blender文件中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。在面对这种情况时,你有两个选择,一是汇报给开发者,等待开发者主动支持,二是自行编译该库(仅建议有丰富计算机知识的人这样做)。
|
||||||
|
Reference in New Issue
Block a user