update doc

yyc12345 · Jan 14, 2024 · 200ac40 · 200ac40
1 parent 25091a4
commit 200ac40
Show file tree

Hide file tree

Showing 20 changed files with 213 additions and 12 deletions.
diff --git a/docs/docs/imgs/grouping.png b/docs/docs/imgs/grouping.png
diff --git a/docs/docs/imgs/naming-convention.png b/docs/docs/imgs/naming-convention.png
diff --git a/docs/docs/imgs/virtools-group.png b/docs/docs/imgs/virtools-group.png
diff --git a/docs/docs/imgs/virtools-material.png b/docs/docs/imgs/virtools-material.png
diff --git a/docs/docs/imgs/virtools-texture.png b/docs/docs/imgs/virtools-texture.png
diff --git a/docs/docs/zh-cn/bme-adder.md 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
@@ -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
@@ -0,0 +1,4 @@
+# 添加机关
+
+!!! info "制作中..."
+    手册的这部分还在制作当中。稍安勿躁。
diff --git 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
@@ -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
@@ -0,0 +1,4 @@
+# 导入导出Virtools文档
+
+!!! info "制作中..."
+    手册的这部分还在制作当中。稍安勿躁。
diff --git 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
@@ -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
@@ -0,0 +1,4 @@
+# 传统对齐
+
+!!! info "制作中..."
+    手册的这部分还在制作当中。稍安勿躁。
diff --git a/docs/docs/zh-cn/naming-convention.md 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
@@ -0,0 +1,4 @@
+# 添加钢轨
+
+!!! info "制作中..."
+    手册的这部分还在制作当中。稍安勿躁。
diff --git a/docs/docs/zh-cn/report-bugs.md 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
@@ -0,0 +1,4 @@
+# UV贴图
+
+!!! info "制作中..."
+    手册的这部分还在制作当中。稍安勿躁。
diff --git a/docs/docs/zh-cn/virtools-properties.md 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
@@ -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: