diff --git a/docs/docs/imgs/grouping.png b/docs/docs/imgs/grouping.png new file mode 100644 index 0000000..2ee9996 Binary files /dev/null and b/docs/docs/imgs/grouping.png differ diff --git a/docs/docs/imgs/naming-convention.png b/docs/docs/imgs/naming-convention.png new file mode 100644 index 0000000..799010f Binary files /dev/null and b/docs/docs/imgs/naming-convention.png differ diff --git a/docs/docs/imgs/virtools-group.png b/docs/docs/imgs/virtools-group.png new file mode 100644 index 0000000..0ceb4b3 Binary files /dev/null and b/docs/docs/imgs/virtools-group.png differ diff --git a/docs/docs/imgs/virtools-material.png b/docs/docs/imgs/virtools-material.png new file mode 100644 index 0000000..ba4c8b4 Binary files /dev/null and b/docs/docs/imgs/virtools-material.png differ diff --git a/docs/docs/imgs/virtools-texture.png b/docs/docs/imgs/virtools-texture.png new file mode 100644 index 0000000..0e148a8 Binary files /dev/null and b/docs/docs/imgs/virtools-texture.png differ diff --git a/docs/docs/zh-cn/bme-adder.md b/docs/docs/zh-cn/bme-adder.md new file mode 100644 index 0000000..9b71694 --- /dev/null +++ b/docs/docs/zh-cn/bme-adder.md @@ -0,0 +1,4 @@ +# 添加路面 + +!!! info "制作中..." + 手册的这部分还在制作当中。稍安勿躁。 diff --git a/docs/docs/zh-cn/compile-distribute-plugin.md b/docs/docs/zh-cn/compile-distribute-plugin.md index 7512f20..b10f47e 100644 --- a/docs/docs/zh-cn/compile-distribute-plugin.md +++ b/docs/docs/zh-cn/compile-distribute-plugin.md @@ -1,3 +1,40 @@ # 编译与分发插件 +本页面将指导你编译插件以及分发它。 +## 编译LibCmo与BMap + +BBP的Virtools文件原生导入导出功能依赖BMap以及其Python绑定PyBMap来实现。为了分发插件,我们需要首先编译BMap及其前置LibCmo。而在编译前,你需要先确认你需要的BMap版本。因为BBP并不总是使用最新的BMap,例如你正在编译一个旧版的BBP,其显然不可能依赖最新的BMap。BMap也在不断升级中,其提供的功能也在不断变化,不同版本的BMap是不兼容的。BBP通常会在发布时写明其所用的BMap版本,如果BBP没有指出,你可能需要寻找与BBP发布时最近的BMap版本来编译。 + +在明确版本后,你需要访问[LibCmo位于GitHub的存储库](https://github.com/yyc12345/libcmo21)。然后克隆项目,使用Git命令转到对应版本(或者直接下载对应版本的源码)。然后按照LibCmo的编译手册编译得到BMap。在Windows上,你通常会得到`BMap.dll`和`BMap.pdb`这两个文件。而在Linux上,则会是`BMap.so`。 + +然后我们需要配置PyBMap。PyBMap是随LibCmo一起提供的。请按照PyBMap的手册,将编译得到的二进制BMap库,和PyBMap结合在一起。即完成PyBMap配置。 + +然后我们需要将配置好的PyBMap拷贝到本项目的`bbp_ng/PyBMap`下即可完成此步。 + +## 生成缩略图和压缩JSON + +BBP内置了一系列自定义图标,以及其组件BME需要的用于描述结构的JSON文件。通过批量生成缩略图和压缩JSON的操作,可以减小这些部分的大小,使得其适合在Blender中加载,也更方便分发。 + +转到`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`文件夹下。 + +## 打包 + +将`bbp_ng`文件夹压缩成ZIP文件即可完成打包工作。需要注意的是下列文件或文件夹不应被打包: + +* `bbp_ng/raw_icons`:原始图片文件夹。 +* `bbp_ng/raw_jsons`:原始JSON文件夹。 +* `bbp_ng/.style.yapf`:代码风格描述文件 +* `bbp_ng/.gitignore`:gitignore +* `bbp_ng/icons/.gitkeep`:文件夹占位符 +* `bbp_ng/jsons/.gitkeep`:文件夹占位符 + +打包后的ZIP文件打开后如果有且只有`bbp_ng`一个文件夹,则代表打包成功。切勿直接将`bbp_ng` **内部的文件** 直接打包到ZIP文件中。 + +这样打包后的ZIP文件既可以直接通过Blender插件的安装功能直接安装,也可以解压在插件目录下完成安装。 + +## 生成帮助文档 + +虽然本项目会利用GitHub Page功能提供帮助文档,但有时您可能需要提供帮助文档的离线版本,本节将会介绍如何生成离线版本的帮助文档。 + +首先您需要通过pip安装`mkdocs`和`pymdown-extensions`。然后转到`docs`文件夹下,运行`mkdocs build --no-directory-urls`。运行命令后得到一个名为`site`的文件夹,其中就是可以离线浏览的帮助文档。 diff --git a/docs/docs/zh-cn/component-adder.md b/docs/docs/zh-cn/component-adder.md new file mode 100644 index 0000000..c822ee3 --- /dev/null +++ b/docs/docs/zh-cn/component-adder.md @@ -0,0 +1,4 @@ +# 添加机关 + +!!! info "制作中..." + 手册的这部分还在制作当中。稍安勿躁。 diff --git a/docs/docs/zh-cn/configure-plugin.md b/docs/docs/zh-cn/configure-plugin.md index 27c25aa..017d4a0 100644 --- a/docs/docs/zh-cn/configure-plugin.md +++ b/docs/docs/zh-cn/configure-plugin.md @@ -7,7 +7,7 @@ ## 打开配置面板 -开启Blender,选择`编辑 - 偏好设置`,在打开的窗口中转到`插件`选项卡,在`社区`分类下找到BBP插件,名称为`Object: Ballance Blender Plugin`。请确保其左侧的勾已被选中,代表插件已被启用。点击勾左侧的三角箭头展开插件详细信息,如图所示,进入配置面板。 +开启Blender,选择`Edit - Preferences`,在打开的窗口中转到`Add-ons`选项卡,在`Community`分类下找到BBP插件,名称为`Object: Ballance Blender Plugin`。请确保其左侧的勾已被选中,代表插件已被启用。点击勾左侧的三角箭头展开插件详细信息,如图所示,进入配置面板。 ![](../imgs/config-plugin.png) diff --git a/docs/docs/zh-cn/group-operations.md b/docs/docs/zh-cn/group-operations.md new file mode 100644 index 0000000..7252f6b --- /dev/null +++ b/docs/docs/zh-cn/group-operations.md @@ -0,0 +1,32 @@ +# 按组操作 + +!!! info "制作中..." + 手册的这部分还在制作当中。稍安勿躁。 + +## 按组选择 + +`Ballance - Select by Virtools Group`提供了一种按照Virtools归组数据进行筛选的功能。 + +该功能首先有5种不同的选择策略,与Blender的选择方法完全匹配(开始、扩选、相减、反转、相交)。只需像Blender选择那样使用它。然后,选择你需要的组的名称,然后开始一次选择或筛选。 + +!!! note "关于模式选择" + 如果可以,请尽可能使用相减或相交模式。因为这样可以避免分析过多的物体。例如先选定一个大致的范围,然后使用相交模式过滤,比直接使用开始模式效率更高。 + +## 快速归组 + +BBP插件在2个地方添加了为物体快速归组的功能。首先是物体上下文菜单:你可以选择一系列物体,然后右键,在物体上下文菜单中找到快速归组功能。其次是大纲视图中的物体菜单:你可以在大纲窗口中,右键选择的物体,找到快速归组功能。两者菜单如下图所示。 + +![](../imgs/grouping.png) + +### Group into... + +把选择物体归入你选择的组。 + +### Ungroup from... + +把选择物体从你选择的组中取消归组。 + +### Clear All Groups + +清空选择物体的所有归组信息。执行前会让你确认以免误操作。 + diff --git a/docs/docs/zh-cn/import-export-virtools.md b/docs/docs/zh-cn/import-export-virtools.md new file mode 100644 index 0000000..2ab9b9b --- /dev/null +++ b/docs/docs/zh-cn/import-export-virtools.md @@ -0,0 +1,4 @@ +# 导入导出Virtools文档 + +!!! info "制作中..." + 手册的这部分还在制作当中。稍安勿躁。 diff --git a/docs/docs/zh-cn/index.md b/docs/docs/zh-cn/index.md index bf38451..78d991e 100644 --- a/docs/docs/zh-cn/index.md +++ b/docs/docs/zh-cn/index.md @@ -16,19 +16,22 @@ Ballance Blender Plugin(后文简称BBP)是一款关注Ballance自制地图 * [安装插件](./install-plugin.md) * [配置插件](./configure-plugin.md) -## 基础 +## 特性 -* Virtools属性 -* 导入导出Virtools文档 -* 按组操作 -* 高级贴图 -* 添加预制结构 -* 添加钢轨 -* 添加机关 +* [Virtools属性](./virtools-properties.md) +* [导入导出Virtools文档](./import-export-virtools.md) +* [按组操作](./group-operations.md) +* [传统对齐](./legacy-align.md) +* [命名规则](./naming-convention.md) +* [UV贴图](./uv-mapping.md) +* [添加路面](./bme-adder.md) +* [添加钢轨](./rail-adder.md) +* [添加机关](./component-adder.md) -## 进阶 +## 其它 * [编译与分发插件](./compile-distribute-plugin.md) +* [报告问题](./report-bugs.md) * [技术信息](./tech-infos.md) !!! info "这些并不是全部" diff --git a/docs/docs/zh-cn/install-plugin.md b/docs/docs/zh-cn/install-plugin.md index 082bdb1..aee8aaa 100644 --- a/docs/docs/zh-cn/install-plugin.md +++ b/docs/docs/zh-cn/install-plugin.md @@ -36,11 +36,11 @@ BBP对Blender支持的原则是支持当前最新的 **LTS** 版本,在最新 ## 安装插件 -开启Blender,选择`编辑 - 偏好设置`,在打开的窗口中转到`插件`选项卡,点击`安装`按钮,选择刚刚下载完毕的ZIP压缩包,即可安装完成。若没有在列表中看到可选择刷新按钮或重启Blender。 +开启Blender,选择`Edit - Preferences`,在打开的窗口中转到`Add-ons`选项卡,点击`Install...`按钮,选择刚刚下载完毕的ZIP压缩包,即可安装完成。若没有在列表中看到可选择刷新按钮或重启Blender。 您也可以选择手动安装插件(如果上述安装方法失败了的话),转到`Blender/3.6/scripts/addons`,将下载好的ZIP压缩包内容解压到此文件夹下,启动Blender,即可在插件列表中找到BBP。 -BBP插件位于`社区`类别下,名称为`Object: Ballance Blender Plugin`,找到后勾选名称左侧的勾即可启用插件。插件安装成功后的偏好设置页面如下图所示。 +BBP插件位于`Community`类别下,名称为`Object: Ballance Blender Plugin`,找到后勾选名称左侧的勾即可启用插件。插件安装成功后的偏好设置页面如下图所示。 ![](../imgs/config-plugin.png) diff --git a/docs/docs/zh-cn/legacy-align.md b/docs/docs/zh-cn/legacy-align.md new file mode 100644 index 0000000..c9eb615 --- /dev/null +++ b/docs/docs/zh-cn/legacy-align.md @@ -0,0 +1,4 @@ +# 传统对齐 + +!!! info "制作中..." + 手册的这部分还在制作当中。稍安勿躁。 diff --git a/docs/docs/zh-cn/naming-convention.md b/docs/docs/zh-cn/naming-convention.md new file mode 100644 index 0000000..37fbd48 --- /dev/null +++ b/docs/docs/zh-cn/naming-convention.md @@ -0,0 +1,32 @@ +# 命名规则 + +!!! info "制作中..." + 手册的这部分还在制作当中。稍安勿躁。 + +## 自动归组与重命名 + +在大纲视图中,对任意集合右键,可以得到自动归组与重命名菜单。 + +![](../imgs/naming-convention.png) + +本插件目前支持两种命名标准。 +其一为技术信息章节已经阐述的制图链标准,在本插件中的名称为`YYC Tools Chains`。 +其二为[Imengyu/Ballance](https://github.com/imengyu/Ballance)所用命名标准,在本插件中的名称为`Imengyu Ballance`。 + +这些功能最终只会展示成功与否的一个概括性消息。如果您需要详细查看某个物体为什么不能转换,请点击`Window - Toggle System Console`,插件在那里有更详细的输出。 + +### Rename by Group + +根据当前物体的归组信息,为其重命名为合适的名称。 +这通常用在迁移原版地图的过程中。一些Ballance衍生程序没有Virtools组概念,因此需要依赖名称来取得归组信息。 + +### Convert Name + +在不同命名标准之间切换。 +通常用于在不同Ballance衍生程序中进行转换。 + +### Auto Grouping + +根据给定的命名标准,为物体自动填充归组信息。 +需要注意的是,原有的归组信息会被覆盖。 +在制图过程中,如果你遵守了某些命名标准,则此功能可以为你自动完成归组功能。 diff --git a/docs/docs/zh-cn/rail-adder.md b/docs/docs/zh-cn/rail-adder.md new file mode 100644 index 0000000..5f755ee --- /dev/null +++ b/docs/docs/zh-cn/rail-adder.md @@ -0,0 +1,4 @@ +# 添加钢轨 + +!!! info "制作中..." + 手册的这部分还在制作当中。稍安勿躁。 diff --git a/docs/docs/zh-cn/report-bugs.md b/docs/docs/zh-cn/report-bugs.md new file mode 100644 index 0000000..036b3a4 --- /dev/null +++ b/docs/docs/zh-cn/report-bugs.md @@ -0,0 +1,29 @@ +# 报告问题 + +## 什么会出错 + +BBP不是完美的,由于BBP的Virtools文件导入导出模块是由C++编写的,因此BBP比其他插件更容易出错,且出错的后果可能会更严重(包括但不限于内存泄漏,误删除用户文件(像[少前2事件](https://www.163.com/dy/article/IGUHP2TE0526D7OK.html)一样)等)。 + +在Blender中,如果插件执行出错,你将会观察到: + +* 期待的效果没有达成 +* 鼠标处弹出一大堆你看不懂的堆栈输出文本 +* 使用`Window - Toggle System Console`打开控制台后,可以观察到Python的异常输出。 + +## 哪部分出错了 + +对于BBP插件而言,如果你在Python异常输出中观察到类似于`BMap operation failed`的字样,或者在`Blender/3.6/scripts/addons/bbp_ng/PyBMap`文件夹下观察到了`IronPad.log`文件,则说明BBP插件的由C++编写的BMap部分出错了,**您需要立即保存您当前的Blender文档,并退出Blender。** 因为此时插件已处于非正常状态,您不应继续任何操作。 + +如果并没有上述情况,那么这就只是普通的Python代码执行错误,不需要过度担心,但错误仍然是致命的,建议做完所有必要的操作后退出Blender并报告错误。 + +## 向何处报告 + +如果你有GitHub账户,你可以在[BBP的存储库的Issue页面](https://github.com/yyc12345/BallanceBlenderHelper/issues)中创建并汇报问题。 + +如果做不到,则直接汇报给插件作者也是可以的。 + +## 报告的内容 + +首先你需要详细描述你是如何出发这个错误的,这个错误有什么结果。如果可以上传导致错误的文档,请尽量上传(如果不方便公开发布,可以通过邮件等私有渠道发送给作者)。 + +您还需要提供Blender控制台中输出的Python堆栈报告(使用`Window - Toggle System Console`打开控制台)。如果你的错误是BMap部分的错误,您还需要提供`Blender/3.6/scripts/addons/bbp_ng/PyBMap`文件夹下的`IronPad.log`和`IronPad.dmp`文件以方便开发者定位错误。 diff --git a/docs/docs/zh-cn/uv-mapping.md b/docs/docs/zh-cn/uv-mapping.md new file mode 100644 index 0000000..8bc9563 --- /dev/null +++ b/docs/docs/zh-cn/uv-mapping.md @@ -0,0 +1,4 @@ +# UV贴图 + +!!! info "制作中..." + 手册的这部分还在制作当中。稍安勿躁。 diff --git a/docs/docs/zh-cn/virtools-properties.md b/docs/docs/zh-cn/virtools-properties.md new file mode 100644 index 0000000..4e9eeea --- /dev/null +++ b/docs/docs/zh-cn/virtools-properties.md @@ -0,0 +1,34 @@ +# Virtools属性 + +!!! info "制作中..." + 手册的这部分还在制作当中。稍安勿躁。 + +## Virtools组 + +BBP插件为每一个Blender物体添加了新的属性,被称为Virtools Group。与Virtools中的组具有相同的功能。选择一个物体,在`Object`属性面板可以找到`Virtools Group`面板。 + +![](../imgs/virtools-group.png) + +在`Virtools Group`面板中,可以点击添加为物体归组。在点击添加按钮后,可以选择预定义,然后从所有合法的Ballance组名中选择一个添加。或选择自定义,然后输入你想要的组名添加。也可以点击删除按钮,删除选中的Virtools组。最后,可以通过点击垃圾桶按钮一次性删除这个物体的所有组数据(删除前会让你确认)。 + +BBP还在Blender的其它菜单提供了对Virtools组的访问,具体内容请参阅[按组操作](./group-operations.md)。 + +## Virtools材质 + +插件为每一个Blender材质添加了新的属性,被称为Virtools Material。它在Virtools材质与Blender材质之间架起沟通的桥梁。转到`Material`属性面板,选择一个材质,即可以找到`Virtools Material`面板。 + +![](../imgs/virtools-material.png) + +可以在`Virtools Material`面板中设置材质属性,就像在Virtools中操作一般。`Virtools Material`面板中所有的材质参数均为Virtools中材质参数的映射,将准确地反映到最后保存的Virtools文档中。 + +`Virtools Material`面板提供了预设功能,点击顶部的`Preset`按钮即可开始进行预设。预设功能允许用户使用一些预设的材质设置,例如路面顶面,侧面的材质数据等,方便使用。需要注意的是,使用预设不会影响材质的贴图选项,当应用预设后,您仍然需要手动设置材质的贴图。 + +`Virtools Material`面板同样提供把`Virtools Material`面板中的材质数据反应到Blender材质上的功能,以在Blender中获得可视的效果。点击顶部的`Apply`按钮即可执行此功能。当您在Blender中保存Virtools文档时,Virtools文档中的材质数据将从`Virtools Material`面板中指定的数值获取,而不会从Blender材质中获取。这意味一个正确的材质设置过程是:先在`Virtools Material`面板中编辑材质参数,然后使用`Apply`按钮将其反映到Blender材质上,而不是直接去编辑Blender材质。 + +TODO: 添加有关贴图选择按钮的帮助内容 + +## Virtools贴图 + +TODO... + +![](../imgs/virtools-texture.png) diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 3e6f20e..66dc3a9 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -12,7 +12,17 @@ nav: - '开始': 'zh-cn/index.md' - '安装插件': 'zh-cn/install-plugin.md' - '配置插件': 'zh-cn/configure-plugin.md' + - 'Virtools属性': 'zh-cn/virtools-properties.md' + - '导入导出Virtools文档': 'zh-cn/import-export-virtools.md' + - '按组操作': 'zh-cn/group-operations.md' + - '传统对齐': 'zh-cn/legacy-align.md' + - '命名规则': 'zh-cn/naming-convention.md' + - 'UV贴图': 'zh-cn/uv-mapping.md' + - '添加路面': 'zh-cn/bme-adder.md' + - '添加钢轨': 'zh-cn/rail-adder.md' + - '添加机关': 'zh-cn/component-adder.md' - '编译与分发插件': 'zh-cn/compile-distribute-plugin.md' + - '报告问题': 'zh-cn/report-bugs.md' - '技术信息': 'zh-cn/tech-infos.md' theme: