From 9211b0bccaebdaa8d3ceaa856bed1087a6bd64bb Mon Sep 17 00:00:00 2001 From: yyc12345 Date: Tue, 3 Jan 2023 14:43:12 +0800 Subject: [PATCH] translate engrish document and promote zh document --- README.md | 160 ++++++++++++++++++++++++++++++++++++++++----------- README_ZH.md | 29 ++++++---- 2 files changed, 146 insertions(+), 43 deletions(-) diff --git a/README.md b/README.md index cd62dbb..fa590d0 100644 --- a/README.md +++ b/README.md @@ -2,61 +2,73 @@ [中文版本](README_ZH.md) -## Brief introduction +## Brief Introduction -This is a Blender plugin which is served for Ballance mapping in Blender. +This is a Blender plugin which is served for Ballance mapping in Blender. +The latest commit may not be stable to use, please use the latest commit with git tag as the stable version. +This plugin contain various aspect of Ballance mapping. However, if some features can be easily gotten from other Blender plugin, this plugin will not provide them duplicatedly. We highly recommend that use this plugin with following plugins. -The latest commit may not be stable to use, please visit the Release page to get a stable version. +* [BenjaminSauder/SimpleLattice](https://github.com/BenjaminSauder/SimpleLattice): Create lattice quickly to transform object. +* [egtwobits/Mesh Align Plus](https://github.com/egtwobits/mesh_mesh_align_plus): Provide powerful align functions which far beyond vanilla Blender align function. -## Technical infomation - -Used BM file spec can be found in [there](https://github.com/yyc12345/gist/blob/master/BMFileSpec/BMSpec_ZH.md)(Chinese only). - -Used tools chain principle and the file format located in `meshes` can be found in [there](https://github.com/yyc12345/gist/blob/master/BMFileSpec/YYCToolsChainSpec_ZH.md)(Chinese only). +## Technical Infomation +Used BM file spec can be found in [there](https://github.com/yyc12345/gist/blob/master/BMFileSpec/BMSpec_ZH.md)(Chinese only). +Used tools chain principle and the file format located in `meshes` can be found in [there](https://github.com/yyc12345/gist/blob/master/BMFileSpec/YYCToolsChainSpec_ZH.md)(Chinese only). The format of the files which are under the `jsons` folder and belong to the BMERevenge section, can be found in [here](https://github.com/yyc12345/gist/blob/master/BMERevenge/DevDocument_ZH.md) -This plugin will continuously support Blender lastest **LTS** version. This plugin will migrate to new version when the new LTS version released. Currently, it based on Blender 2.83.x. +This plugin will continuously support Blender lastest **LTS** version. This plugin will migrate to new version when the new LTS version released. Currently, it based on Blender **3.3.x**. -## Function introduction +## Installation -### Plugin settings +Put `ballance_blender_plugin` into Blender's plugin folder, `scripts/addons_contrib`. Then enable this plugin in Blender's preferences (DO NOT forget to configure this plugin's settings after first installation or updating plugin.). -* External texture folder: Please fill in the Texture directory of Ballance, the plugin will call the external texture file from this directory (the texture file originally with Ballance) -* No component collection: Objects in this collection will be forced to be set as non-Component. If left blank, this function will be shutdown. -* Temp texture folder: used to cache texture files extracted from BM files. Please arrange a directory that will not be automatically cleaned up. Since Blender will continue to read texture files from this directory, it cannot be emptied at will. And it also does not allow files with the same name to exist, that is, if I import two BMs for two maps, and there are two files with the same name but different images in the two BMs, the later files will overwrite the previous files , And in turn caused a texture error when the first blender document was opened again. For solving this problem, please refer to the subsequent BM import / export +## Feature Introduction + +### Plugin Settings + +* External Texture Folder: Please fill in the `Texture` directory of Ballance, the plugin will refer the external texture file from this directory (the texture file originally with Ballance) +* No Component Collection: Objects located in this collection will be forced to be set as non-component. If left blank, this function will be shutdown. This function is frequently used in forced component replacement. +* Temp Texture Folder: used to cache texture files extracted from BM files. Please arrange a directory that will not be automatically cleaned up. Since Blender will continue to read texture files from this directory, it can not be emptied casually. + +Temp Texture Folder does not allow files with duplicated name. Because of this, imagine this situation, there are two texture files with the same name in two BM files, but they represent different images. When you import them one by one for different maps. The later file will overwrite the previous file, And this will cause a texture error when the first Blender document was opened again. For the solution of this issue, the best way is to force packaging once. After successfully importing the BM, click `File - External Data - Pack Resources`, then you can clear Temp Texture Folder safely. With your preference, you also can click `File - External Data - Unpack Resources` to extract textures. This operation will extract and re-refer all textures into standalone texture folder within the folder where this Blender document is. ### BM import / export -For import, in order to prevent texture errors, the best way is to force packaging once. After successfully importing the BM, choose to pack all into the blend file, and then clear the directory where the Temp texture folder is located, and then click Unpack to file if necessary, this operation will re-depend the textures in the texture library under the project folder. +Click `File - Import - Ballance Map` to import BM file. +When name conflicts occur during importing BM, you have ability to choose different strategies for 4 different data types, Texture, Material, Mesh and Object. You can specify them to create a new instance or use current data block. -For export, you can choose to export a collection or an object (Export mode), and specify the target (Export target). +Click `File - Export - Ballance Map` to export a BM file. +You can export a collection or an object (Export Mode), and specify target (Export Target) correspondingly. +Although plugin provide Virtools Group feature and give you ability to grouping object in Blender. The export function also depend on Tools Chain Principle. Because of this, if you do not follow Tools Chain Principle, some convenient features will be disabled, for example, your exported BM file may larger than common one. -It should be noted that once the BM is exported, all the faces in the file will be converted to triangular faces, please make a backup in advance. And it is recommended to use a flat collection structure, do not put a collections within another collection, which may cause some unnecessary problems. +It should be noted that once the BM is exported, all the faces in the file will be converted to triangular faces, please make a backup in advance. +It is recommended to use a flat collection structure, do not put a collection within another collection, which may cause some unnecessary problems. +The suffix name of BM file is BMX, X stands for compression. BMX and BM is the same thing. ### Ballance 3D -Ballance 3D is a set of light tools related to 3D operations, which can be found in the upper right corner of the 3D view. +Ballance 3D is a set of light tools related to 3D operations, which can be found in the upper left corner menu bar of 3D View. This menu is named as Ballance. #### 3ds Max Align -Provide 3ds Max like align tools. Current active will be seen as reference object. All selected objects(except active object) will be seen as operating object (So you can select multiple objects to align to the reference object). +Provide 3ds Max like align tools. Current active object will be seen as reference object. All selected objects (except active object) will be seen as operating object (So you can select multiple objects to align to a single object). #### Create Rail UV -To create UVs for the rails in the map, you need to select the objects that need to add UVs similar to the rails, and then click this button to create. - -In the dialog, you can select the material to be used. You can also choose the unfolding mode. For shorter rails, you can choose Point mode. For longer rails, you can use Uniform mode. If you need to manually adjust the zoom ratio, please select Scale mode and specify the ratio (not recommended). - -You can also select the projection axis for better UV distribution. +To create UVs for the rails in the map, you need to select the objects that need to add UVs similar to the rails, and then click this button to create. +In the dialog, you can select the material to be used. You can also choose the unfolding mode. In some unfolding modes, projection axis and zoom ratio options is available. Although Ballance will process all rail UV in game internally, it is essential that give a perfect UV in designer. +If you want that the rail have in-game UV (it represent as smooth texture), you can choose `TT_ReflectionMapping` unfolding mode. This mode is written with the reverse work of game used function. This unfolding mode may be useful when you creating advertisement image in Blender for your map. #### Flatten UV -In the object editing mode, it is a operator which is used to attach the currently selected surface to the UV. And you can specific the edge which will be attached into the V axis. Note that only convex faces are supported. +In the object editing mode, it is a operator which is used to attach the currently selected surface to the UV. And you can specific the edge which will be attached into the V axis. +Note that only convex face is supported. Applying this for a concave face will cause undefined behavior. -In the edit mode, select the surface, click Flatten UV, and then scroll the slider to select an edge as a reference. If the generated UV is not attached correctly, such as the FloorSide's band is pasted to the bottom, you can reselect the reference edge and redo the operation until it is correct. +In the edit mode, select the surface, click Flatten UV, and then scroll the slider to select an edge as a reference. +If the generated UV is not attached correctly, such as the FloorSide's band is pasted to the bottom, you can reselect the reference edge and redo the operation until it is correct. -### Add Menu +### Quick Struct Adder In the add menu, we have added a set of commonly used objects. After adding, the object will move to the 3D cursor. @@ -66,15 +78,99 @@ Add elements, you can also specify attributes such as section when adding (it wi #### Rail section -Add rail section, you can choose monorail or rail (just decide the number of rail section loops added, and will not help you rotate the angle), as well as rail radius and rail span. +Add rail section, you can choose monorail or rail (just decide the number of rail section loops added, and will not help you rotate the angle), as well as rail radius and rail span (default value is standard value). #### Floors -Adding floor is part of the BMERevenge project. Basic floor is a basic floor component, and Derived floor is a common component composed of basic components. The extension(length) and the side configuration can be set according to its properties. It also has the advantage of reducing vertices. +A powerful floor adder feature belong to the extension of BMERevenge project. +In menu, Basic Floor is basic floor component. Derived Floor is consisted by basic floor components. Commonly, frequently used models are located in Derived Floor section. +After selecting a floor type, you can assign 2 expand value at most, according to its property. You also can use options to decide whether side faces and bottom face can be generated. +Comparing with trditional Ballance Map Editor, this function can massively reduce useless vertices. -It is recommended to merge the vertices by distance, unless there is a need to delete the surface after adding it +The floor type can be simply grouped as Flat Floor, Sink Floor, Wide Floor and Platform. +Additionally, Trafo Block and Transition between Flat Floor and Sink Floor are available. -## Install +It is recommended to merge the vertices by distance, unless you need do some special work. -Put `ballance_blender_plugin` into Blender's plugin folder, `scripts/addons_contrib`. Then enable this plugin in Blender's preferences (Don't forget to configure this plugin's settings). +### Virtools Group + +Plugin add a new property for each Blender objects, called Virtools Group. It takes the same functionality of Group in Virtools. +Select an object, You can find `Virtools Group` panel in `Object Properties` panel. +Click Add or Delete icon to group or ungroup for object. +Double click item in list to rename it. + +After click Add button, you can choose Predefined option, and select a name from all legal Ballance used group names. +Or, choose Custom option and write your own group name. + +### Virtools Material + +Plugin add a new property for each Blender materials, called Virtools Material. It create a bridge between Virtools Material and Blender Material. +Navigate to `Material Properties` panel, select a material, you can find `Virtools Material` panel. +In default, user created material will not enable Virtools Material feature. You need to click checkbox of `Virtools Material` panel to enable or disable it. + +After enable Virtools Material, `Basic Parameters` section and `Advanced Parameters` section can be set. Set your material peroperties just like operating in Virtools. +Just like its name, `Basic Parameters` is basic material properties. `Advanced Parameters` is mainly related to transparent properties and usually used in the bottom of transparent column. + +In `Operation` section, `Apply Virtools Material` will clean all existed Blender material and create a new material graph according to Virtools material properties. +And, `Parse from Blender Principled BSDF` will try parsing a Principled BSDF to Virtools material. +If your material highly rely on Blender material, please execute `Parse from Blender Principled BSDF` or disable Virtools Material feature before exporting BM file, otherwise material can not be saved correctly. + +### Select by Group + +Plugin add 2 selection functions according to Virtools Group in Select menu. + +#### Select by Virtools Group + +Select objects in active collection according to its Virtools Group properties. +The hidden object also can be selected if you check `Ignore Hide Property`. +Check `Merge Selection` will merge current selection and previous selection. + +#### Filter by Virtools Group + +Filter current selected object by its Virtools Group properties. +Check `Reverse` remove objects matching the requirements, not keep them. + +### Quick Grouping + +Plugin add quick grouping menu in 2 places. +You can select various objects, right click and find quick grouping menu in Object Context menu. +Also you can pick objects in Outline View and right click them, find quick grouping menu in Object menu. + +#### Group into + +Group selected objects into your specified group. + +#### Ungroup from + +Ungroup selected objects from your specified group. + +#### Clear Grouping + +Clean the grouping infomation for selected objects. + +### Auto Grouping & Rename + +In Outline View, you can find auto grouping and rename menu via right click any collection. + +This plugin now support 2 name standard. +First one has been introduced in Technical Infomation chapter. In plugin, its name is `YYC Tools Chains`. +The second one is used by [Imengyu/Ballance](https://github.com/imengyu/Ballance). In plugin, its name is `Imengyu Ballance`. + +All functions within this menu will only output a summary when finishing. If you want to check out some objects in detail, please click `Window - Switch System Terminal`. Plugin output a detailed report in that place. + +#### Rename by Group + +Rename object with proper name according to its Virtools Group properties. +This usually use when migrating original map. Some Ballance derived applications do not have Group concept. They rely on name to get group infomations. + +#### Convert Name + +Convert name between different name standard. +Frequently used in convertion between 2 different Ballance derived applications. + +#### Auto Grouping + +Auto grouping according to specified name standard. +Please pay attention that previous grouping infomations will be overwritten. +If you following some mapping standard during all mapping stages, this function will auto grouping all objects for you. diff --git a/README_ZH.md b/README_ZH.md index d405ac4..8cc0b3b 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -5,7 +5,7 @@ ## 简介 这是一个用于Blender的插件，其主要是服务于Ballance制图。 -请使用拥有最新tag的commit内的代码。最新的commit不能保证其是稳定可用的。 +请选择打了tag的最新commit使用。最新的commit不能保证其是稳定可用的。 本插件囊括了Ballance制图中可能会用到的各种功能。对于一些其它插件可以提供的功能，本插件不再重复提供。建议与下列插件合用以取得更好制图效果： * [BenjaminSauder/SimpleLattice](https://github.com/BenjaminSauder/SimpleLattice)：快速创建晶格以便变形物体。 @@ -17,17 +17,17 @@ 使用的制图链标准以及`meshes`文件夹下的文件的格式可以在[这里](https://github.com/yyc12345/gist/blob/master/BMFileSpec/YYCToolsChainSpec_ZH.md)查找 `jsons`文件夹下的，隶属于BMERevenge部分的文件的格式可以在[这里](https://github.com/yyc12345/gist/blob/master/BMERevenge/DevDocument_ZH.md)查找 -支持Blender的原则是支持当前最新的 **LTS** 版本，在最新的LTS版本释出之后会花一些时间迁移插件。当前插件基于3.3.x版本 +支持Blender的原则是支持当前最新的 **LTS** 版本，在最新的LTS版本释出之后会花一些时间迁移插件。当前插件基于**3.3.x**版本 ## 安装 -将`ballance_blender_plugin`直接复制到Blender插件目录`scripts/addons_contrib`内即可。然后在Blender偏好设置中启用即可（请在第一次使用前或更新插件后配置插件设置）。 +将`ballance_blender_plugin`直接复制到Blender插件目录`scripts/addons_contrib`内即可。然后在Blender偏好设置中启用即可（请在第一次安装后或更新插件后配置插件设置）。 ## 功能介绍 ### 插件设置 -* External texture folder：请填写为Ballance的Texture目录，插件将从此目录下调用外置贴图文件（即Ballance原本带有的贴图文件） +* External texture folder：请填写为Ballance的`Texture`目录，插件将从此目录下调用外置贴图文件（即Ballance原本带有的贴图文件） * No component collection：处于此集合中的物体将被强制指定为非Component。如果留空则表示不需要这个功能。此功能通常用于机关模型强制替换。 * Temp texture folder：用于缓存从BM文件中提取的贴图文件，请安排一个平时不会被自动清理的目录。由于Blender会持续从这个目录读取贴图文件，因此不能随意清空。 @@ -57,7 +57,7 @@ Ballance 3D是一套简单的用于制图3D相关的轻型工具集合，可以 #### Create Rail UV 为地图中的钢轨创建UV，你需要先选中需要添加类似钢轨UV的物体，然后点击这个按钮以创建。 -在弹出设置窗口中，可以选择使用的材质。还可以选择展开模式，在部分展开模式下，还可以选择投影轴。尽管Ballance最终会为所有钢轨重新上UV，一个在界面中看着赏心悦目的钢轨贴图还是比较重要的。 +在弹出设置窗口中，可以选择使用的材质。还可以选择展开模式，在部分展开模式下，还可以选择投影轴和缩放大小。尽管Ballance最终会为所有钢轨重新上UV，一个在界面中看着赏心悦目的钢轨贴图还是比较重要的。 如果您需要在Blender中呈现游戏内钢轨的贴图效果（表现为所谓的平滑贴图），您可以选择`TT_ReflectionMapping`展开模式。此功能由逆向游戏所用函数得来。这在渲染地图宣传画时可能会很有用。 #### Flatten UV @@ -70,7 +70,7 @@ Ballance 3D是一套简单的用于制图3D相关的轻型工具集合，可以 ### 快速添加结构 -在添加菜单中我们添加了一套较为常用的物体。添加后物体会移动到3D游标处。 +在添加菜单中我们添加了一系列较为常用的物体。添加后物体会移动到3D游标处。 #### Elements @@ -105,13 +105,13 @@ Ballance 3D是一套简单的用于制图3D相关的轻型工具集合，可以 ### Virtools材质 插件为每一个Blender材质添加了新的属性，被称为Virtools Material。它在Virtools材质与Blender材质之间架起沟通的桥梁。 -转到`材质属性`面板，选择一个材质，额可以找到`Virtools Material`面板。 -默认情况下，由用户创建的材质不启用Virtools Material，您可以通过点击Virtools Material的复选框来启用或关闭它。 +转到`材质属性`面板，选择一个材质，即可以找到`Virtools Material`面板。 +默认情况下，由用户创建的材质不启用Virtools Material，您可以通过点击`Virtools Material`面板的复选框来启用或关闭它。 在启用Virtools Material后，可以在`Basic Parameters`和`Advanced Parameters`中设置材质属性，就像在Virtools中操作一般。 `Basic Parameters`是基础材质属性。`Advanced Parameters`则是与透明相关的材质属性，主要用于半透明柱子底部等。 -操作中的`Apply Virtools Material`将把Virtools Material应用到Blender材质上。 +`Operation`中的`Apply Virtools Material`将把Virtools Material应用到Blender材质上。 而`Parse from Blender Principled BSDF`将尝试将一个原理化BSDF转换为Virtools材质数据。 如果您是从Blender材质编辑的，请务必对此材质在导出前执行`Parse from Blender Principled BSDF`，或关闭Virtools Material功能，否则材质将无法正确保存。 @@ -119,13 +119,20 @@ Ballance 3D是一套简单的用于制图3D相关的轻型工具集合，可以 选择菜单中新增了两项按照Virtools归组数据进行筛选的功能。 -`Select by Virtools Group`将对当前活动集合内的物体按照其Virtools Group属性进行筛选。 +#### Select by Virtools Group + +将对当前活动集合内的物体按照其Virtools Group属性进行选择。 勾选`Ignore Hide Property`后，即使是隐藏的物体，也会被筛选。 勾选`Merge Selection`，将会把选中的物体合并到当前选定的内容中。 -`Filter by Virtools Group`将会按照Virtools Group属性，过滤当前选中物体。 +#### Filter by Virtools Group + +将会按照Virtools Group属性，过滤当前选中物体。 勾选`Reverse`将会反向操作，即去除掉符合条件的物体。 +如果可以，请尽可能使用`Filter by Virtools Group`而不是`Select by Virtools Group`。因为这样可以避免分析过多的物体。 +例如先选定一个大致的范围，然后使用`Filter by Virtools Group`过滤，比直接使用`Select by Virtools Group`效率更高。 + ### 快速归组 插件在2个地方添加了为物体快速归组的功能。