From 24ac07a3b3e750f50051148d0c04d6dd7d1cf6d0 Mon Sep 17 00:00:00 2001 From: yyc12345 Date: Thu, 25 Jul 2024 10:37:16 +0800 Subject: [PATCH] doc: translate documentation --- docs/docs/en/bme-adder.md | 33 ++++++++++++++++-- docs/docs/en/compile-distribute-plugin.md | 41 +++++++++++++++++++++-- docs/docs/en/report-bugs.md | 29 ++++++++++++++-- docs/docs/zh-cn/bme-adder.md | 2 +- docs/docs/zh-cn/report-bugs.md | 8 ++--- 5 files changed, 102 insertions(+), 11 deletions(-) diff --git a/docs/docs/en/bme-adder.md b/docs/docs/en/bme-adder.md index db2feec..66bdea3 100644 --- a/docs/docs/en/bme-adder.md +++ b/docs/docs/en/bme-adder.md @@ -1,4 +1,33 @@ # Add Floor -!!! info "Work in Progress" - This part of manual still work in progress. +## Start Generating + +In the 3D view, click `Add - Floors` to expand the Add Floors menu. The menu is shown below. + +![](../imgs/bme-adder.png) + +Click on the menu to see all supported floor types in the submenu that pops up. Their names and icons hint at the style and shape of the floor it is intended to create. + +!!! info "BME is extensible" + BME's floor adder is extensible, each item in the menu is actually described by a set of JSON data. You can read the [Technical Information](./tech-infos.md) section to learn how we write this JSON, and you can even expand the types of floors that BME can create to suit your needs. + +## Configure Floor + +Clicking on one of the floor types will open the floor creation dialog, here we are showing a Normal Platform as shown below. In the dialog, we can configure various properties of this floor type, such as the length, width, height, distance, and whether the surface is displayed or not, to customize the geometry it generates so that it meets our requirements. + +![](../imgs/bme-adder-dialog.png) + +In the Normal Platform dialog, we can first see that it asks us to provide the length and width of the floor, which determines the size of our platform, and there is a text description to help you understand what this property controls. + +Then it also asks us to provide the height of the platform, which defaults to 5, which is the default height of the floor in Ballance. Anything less than 5 creates a thin floor similar to the one in the "The Devil Dragon" map, and anything greater than 5 creates a very high floor wall similar to the one in the "Exaggeratedly Dense Space Station" map. + +Finally, it tells us which sides of the floor we need to configure to display. Note that Top and Bottom are the top and bottom surfaces along the height direction (Z axis), while Front, Back, Left, and Right are the front, back, left, and right surfaces when looking down with your head on the -X axis and your eyes on the -Z axis. You may notice that there is a perspective cube in the center of these six face buttons, and in fact the positions of these six face options correspond to the positions of the six faces of this perspective cube. + +## Tips + +Each floor type has a different number of configuration entries, so for different floor types, you will need to follow the configuration hint text to understand what the corresponding configuration does. Some floor types may have a large number of configuration entries, while others may have no configuration entries at all. + +The default values for the floor type configuration are set to the values that were most commonly used when the floor was created. The values are reset to the defaults each time the floor type is switched or recreated. + + + diff --git a/docs/docs/en/compile-distribute-plugin.md b/docs/docs/en/compile-distribute-plugin.md index 0d58e49..a126909 100644 --- a/docs/docs/en/compile-distribute-plugin.md +++ b/docs/docs/en/compile-distribute-plugin.md @@ -1,4 +1,41 @@ # Compile and Distribute Plugin -!!! info "Work in Progress" - This part of manual still work in progress. +This page will guide you in compiling the plugin as well as distributing it. + +## Compiling LibCmo with BMap + +BBP's Virtools file native import/export functionality relies on BMap and its Python binding PyBMap. In order to distribute the plugin, we need to first compile BMap and its predecessor LibCmo, and before doing so, you need to check the version of BMap you need. Because BBP doesn't always use the latest version of BMap, e.g. if you're compiling an older version of BBP, it's obviously not possible to rely on the latest version of BMap. BMap is constantly being upgraded, and the functionality it provides is constantly changing, and different versions of BMap are incompatible. BBP usually states the version of BMap it uses at the time of release, but if BBP doesn't point it out, you may need to look for the most recent version of BMap that compiles with the version of BBP at the time of its release. + +After specifying the version, you need to visit [LibCmo GitHub repository](https://github.com/yyc12345/libcmo21). Then clone the project and use the Git command to go to the corresponding version (or just download the source code of the corresponding version). Then follow LibCmo's compilation manual to compile to get BMap. on Windows, you'll usually get the files `BMap.dll` and `BMap.pdb`. On Linux, it will be `BMap.so`. + +Then we need to configure PyBMap, which comes with LibCmo. Please follow the manual of PyBMap to combine the compiled binary BMap library with PyBMap. That is to complete the PyBMap configuration. + +Then we need to copy the configured PyBMap to our project under `bbp_ng/PyBMap` to complete this step. + +## Generate Thumbnails and Compress JSON + +BBP comes with a built-in set of custom icons, as well as the JSON files needed by its component BME to describe the structure. By batch generating thumbnails and compressing JSON operations, the size of these parts can be reduced, making them suitable for loading in Blender and easier to distribute. + +Go to the `bbp_ng/tools` folder and run `python3 build_icons.py` which will batch generate thumbnails (this requires the PIL library, please install it via pip in advance). It actually generates thumbnails from the original images in the `bbp_ng/raw_icons` directory and stores them in the `bbp_ng/icons` folder. Running `python3 build_jsons.py` will compress the JSON, which actually reads, compresses, and writes the raw JSON files from the `bbp_ng/raw_jsons` directory into the `bbp_ng/jsons` folder. + +## Packaging + +Starting from Blender 4.2 LTS, plugins are packaged using Blender's own packaging feature. + +Assuming that the final output file is `redist/bbp_ng.zip`. If you are in the root directory of the project, execute the `blender --command extension build --source-dir bbp_ng --output-filepath redist/bbp_ ng.zip` command in a command line window to finish packaging. Please note `blender` is the executable Blender program. + +Blender will package the plugin according to the instructions in `blender_manifest.toml` with the following files excluded: + +* `bbp_ng/raw_icons`: raw thumbnail folder. +* `bbp_ng/raw_jsons`: raw JSON folder. +* `bbp_ng/tools`: tools for compiling. +* `bbp_ng/.style.yapf`: code style description file. +* `bbp_ng/.gitignore`: gitignore +* `bbp_ng/icons/.gitkeep`: folder placeholder +* `bbp_ng/jsons/.gitkeep`: folder placeholder + +## Generating Help Documentation + +Although this project will utilize the GitHub Page feature to provide help documentation, sometimes you may need to provide an offline version of the help documentation, this section will explain how to generate an offline version of the help documentation. + +First you need to install `mkdocs` and `pymdown-extensions` via pip. Then go to the `docs` folder and run `mkdocs build --no-directory-urls`. After running the command you get a folder called `site`, which is the help documentation that can be viewed offline. diff --git a/docs/docs/en/report-bugs.md b/docs/docs/en/report-bugs.md index d68d7ef..d9e2404 100644 --- a/docs/docs/en/report-bugs.md +++ b/docs/docs/en/report-bugs.md @@ -1,4 +1,29 @@ # Report Issue -!!! info "Work in Progress" - This part of manual still work in progress. +## What Can Go Wrong + +BBP is not perfect, and since BBP's Virtools file import/export module is written in C++, BBP is more prone to errors than other plugins, and the consequences of errors can be more serious (including but not limited to memory leaks, accidental deletion of user files, etc.). + +In Blender, you will observe if the plugin execution goes wrong: + +* The expected effect is not achieved +* A large stack of output text pops up at the mouse that you can't read +* After opening the console using `Window - Toggle System Console`, you can observe the Python exception output. + +## What Part Went Wrong + +For the BBP plugin, if you observe something like `BMap operation failed` in the Python exception output, or the `IronPad.log` file in the `/PyBMap` folder, it means that The BBP plugin's BMap section, written in C++, is in error, and **you need to immediately save your current Blender document and exit Blender**. Because the plugin is in an abnormal state at this point, you should not continue any operations. + +If there is no such thing as the above, then this is just a normal Python code execution error and you don't need to worry too much about it, but the error is still fatal and it is recommended to exit Blender and report the error after doing all the necessary operations. + +## Where to Report + +If you have a GitHub account, you can create and report issues in [Issue page of BBP repository](https://github.com/yyc12345/BallanceBlenderHelper/issues). + +If you can't do that and you have proper way to contact with plugin author, then reporting directly to the plugin author is fine. + +## The Content of the Report + +First of all you need to describe in detail how you raise this error and what are the results of this error. If you can upload the documentation that led to the error, please try to do so (if it's not convenient to post it publicly, you can send it to the author through a private way such as email). + +You also need to provide the Python stack report output in the Blender console (use `Window - Toggle System Console` to open the console). If your error is an error in the BMap section, you also need to provide the `IronPad.log` and `IronPad.dmp` files in the `/PyBMap` folder to make it easier for developers to locate the error. diff --git a/docs/docs/zh-cn/bme-adder.md b/docs/docs/zh-cn/bme-adder.md index 8eafc14..e28ccb2 100644 --- a/docs/docs/zh-cn/bme-adder.md +++ b/docs/docs/zh-cn/bme-adder.md @@ -2,7 +2,7 @@ ## 开始生成 -在3D视图中，点击`Add - Floors`可展开添加机关菜单。菜单如下图所示。 +在3D视图中，点击`Add - Floors`可展开添加路面菜单。菜单如下图所示。 ![](../imgs/bme-adder.png) diff --git a/docs/docs/zh-cn/report-bugs.md b/docs/docs/zh-cn/report-bugs.md index e52eb1d..17d7d8b 100644 --- a/docs/docs/zh-cn/report-bugs.md +++ b/docs/docs/zh-cn/report-bugs.md @@ -12,7 +12,7 @@ BBP不是完美的，由于BBP的Virtools文件导入导出模块是由C++编写 ## 哪部分出错了 -对于BBP插件而言，如果你在Python异常输出中观察到类似于`BMap operation failed`的字样，或者在`Blender/3.6/scripts/addons/bbp_ng/PyBMap`文件夹下观察到了`IronPad.log`文件，则说明BBP插件的由C++编写的BMap部分出错了，**你需要立即保存你当前的Blender文档，并退出Blender。** 因为此时插件已处于非正常状态，你不应继续任何操作。 +对于BBP插件而言，如果你在Python异常输出中观察到类似于`BMap operation failed`的字样，或者在`<插件安装位置>/PyBMap`文件夹下观察到了`IronPad.log`文件，则说明BBP插件的由C++编写的BMap部分出错了，**你需要立即保存你当前的Blender文档，并退出Blender。** 因为此时插件已处于非正常状态，你不应继续任何操作。 如果并没有上述情况，那么这就只是普通的Python代码执行错误，不需要过度担心，但错误仍然是致命的，建议做完所有必要的操作后退出Blender并报告错误。 @@ -20,10 +20,10 @@ BBP不是完美的，由于BBP的Virtools文件导入导出模块是由C++编写 如果你有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`文件以方便开发者定位错误。 +你还需要提供Blender控制台中输出的Python堆栈报告（使用`Window - Toggle System Console`打开控制台）。如果你的错误是BMap部分的错误，你还需要提供`<插件安装位置>/PyBMap`文件夹下的`IronPad.log`和`IronPad.dmp`文件以方便开发者定位错误。