fix: fix various trivial issues

- update blender_manifest.toml to the latest version and fix the issues raised by blender when packaging. - use blender do packaging work. remove redist.py because blender_manifest.toml has gitignore like filter feature when packaging. - update document about installing, configurating, building plugin for blender 4.2. - update a document image for blender 4.2.
yyc12345 · Jul 19, 2024 · 427bad4 · 427bad4
1 parent 209d212
commit 427bad4
Show file tree

Hide file tree

Showing 7 changed files with 69 additions and 180 deletions.
diff --git a/bbp_ng/blender_manifest.toml b/bbp_ng/blender_manifest.toml
@@ -8,32 +8,25 @@ schema_version = "1.0.0"
 id = "bbp_ng"
 version = "4.0.0"
 name = "Ballance Blender Plugin"
-tagline = "The specialized add-on served for creating custom game map in Ballance game"
+tagline = "The specialized add-on served for creating game map of Ballance"
 maintainer = "yyc12345 <[email protected]>"
 # Supported types: "add-on", "theme"
 type = "add-on"
 
-# Optional: add-ons can list which resources they will require:
-# * "files" (for access of any filesystem operations)
-# * "network" (for internet access)
-# * "clipboard" (to read and/or write the system clipboard)
-# * "camera" (to capture photos and videos)
-# * "microphone" (to capture audio)
-permissions = ["files"]
-
 # Optional link to documentation, support, source files, etc
 website = "https://github.com/yyc12345/BallanceBlenderHelper"
 
 # Optional list defined by Blender and server, see:
-# https://docs.blender.org/manual/en/dev/extensions/tags.html
+# https://docs.blender.org/manual/en/dev/advanced/extensions/tags.html
 tags = ["Object", "Mesh", "UV", "Import-Export"]
 
 blender_version_min = "4.2.0"
-# Optional: maximum supported Blender version
+# # Optional: Blender version that the extension does not support, earlier versions are supported.
+# # This can be omitted and defined later on the extensions platform if an issue is found.
 # blender_version_max = "5.1.0"
 
 # License conforming to https://spdx.org/licenses/ (use "SPDX: prefix)
-# https://docs.blender.org/manual/en/dev/extensions/licenses.html
+# https://docs.blender.org/manual/en/dev/advanced/extensions/licenses.html
 license = [
   "SPDX:GPL-3.0-or-later",
 ]
@@ -43,13 +36,46 @@ license = [
 #   "1998 Company Name",
 # ]
 
-# Optional list of supported platforms. If ommitted, the extension will be available in all operating systems.
-platforms = ["windows-amd64", "windows-x64", "linux-x86_64", "linux-x64"]
-# Supported platforms: "windows-amd64", "macos-arm64", "linux-x86_64", "windows-arm64", "macos-x86_64"
+# Optional list of supported platforms. If omitted, the extension will be available in all operating systems.
+platforms = ["windows-x64", "linux-x64"]
+# Supported platforms: "windows-x64", "macos-arm64", "linux-x64", "windows-arm64", "macos-x64"
 
 # Optional: bundle 3rd party Python modules.
-# https://docs.blender.org/manual/en/dev/extensions/python_wheels.html
+# https://docs.blender.org/manual/en/dev/advanced/extensions/python_wheels.html
 # wheels = [
 #   "./wheels/hexdump-3.3-py3-none-any.whl",
-#   "./wheels/jsmin-3.0.1-py3-none-any.whl"
-# ]
+#   "./wheels/jsmin-3.0.1-py3-none-any.whl",
+# ]
+
+# Optional: add-ons can list which resources they will require:
+# * files (for access of any filesystem operations)
+# * network (for internet access)
+# * clipboard (to read and/or write the system clipboard)
+# * camera (to capture photos and videos)
+# * microphone (to capture audio)
+#
+# If using network, remember to also check `bpy.app.online_access`
+# https://docs.blender.org/manual/en/dev/advanced/extensions/addons.html#internet-access
+#
+# For each permission it is important to also specify the reason why it is required.
+# Keep this a single short sentence without a period (.) at the end.
+# For longer explanations use the documentation or detail page.
+
+[permissions]
+# network = "Need to sync motion-capture data to server"
+files = "Import/export Virtools file from/to disk"
+# clipboard = "Copy and paste bone transforms"
+
+# Optional: build settings.
+# https://docs.blender.org/manual/en/dev/advanced/extensions/command_line_arguments.html#command-line-args-extension-build
+[build]
+paths_exclude_pattern = [
+  "__pycache__/", # Python runtime cache
+  ".style.yapf", # Python code style
+  "*.gitkeep", # Git directory keeper
+  ".gitignore", # Git Ignore File
+  "*.md", # Useless document.
+  "/raw_jsons", # Raw JSONs.
+  "/raw_icons", # Raw Icons.
+  "/tools", # Assistant tools.
+]
diff --git a/bbp_ng/tools/common.py b/bbp_ng/tools/common.py
@@ -63,84 +63,3 @@ def common_file_migrator(
             dst_file: str = relative_to_folder(src_file, from_folder, to_folder)
             # call handler
             fct_proc_file(src_file, dst_file)
-
-def conditional_file_copy(
-        from_folder: str, to_folder: str,
-        only_copy: tuple[str, ...] | None = None,
-        ignore_copy: tuple[str, ...] | None = None,
-        recursively: bool = False) -> None:
-    """
-    The enhanced file tree copy function used in redist script.
-
-    The name of file or folder will be checked by `only_copy` first,
-    it it decide this file or folder should be copied, we then check whether
-    it is in `ignore_copy`.
-
-    @param from_folder[in] The folder need to be redist.
-    @param to_folder[in] The folder will be placed redist files.
-    @param only_copy[in] An Unix style pathname pattern tuple to instruct which files or folders should be copied, 
-    or None if we want to copy every files and folders.
-    @param ignore_copy[in] An Unix style pathname pattern tuple to instruct which files or folders should not be copied,
-    or None if we want to copy every files and folders.
-    @param recursively[in] Whether recursively copy sub-folders and their files.
-    """
-    # build a helper functions
-    def is_need_copy(checked_filename: str) -> bool:
-        # if only_copy enabled, check it.
-        # if no only_copy, pass the check because file should be copied in default.
-        if only_copy is not None:
-            for only_copy_item in only_copy:
-                # matched, should copy it, break this for syntax
-                if fnmatch.fnmatch(checked_filename, only_copy_item):
-                    break
-            else:
-                # no matched item, this entry should not be copied.
-                return False
-
-        if ignore_copy is not None:
-            # check whether given name is in ignore_copy
-            for ignore_copy_item in ignore_copy:
-                # matched, should not be copied
-                if fnmatch.fnmatch(checked_filename, only_copy_item):
-                    return False
-            # no matched, copy it
-            return True
-        else:
-            # no ignore_copy, directly copy it
-            return True
-
-    # iterate from_folder folder
-    for root, dirs, files in os.walk(from_folder, topdown = True):
-        # create self
-        src_self: str = root
-        dst_self: str = relative_to_folder(src_self, from_folder, to_folder)
-        print(f'Creating: {src_self} -> {dst_self}')
-        os.makedirs(dst_self, exist_ok=True)
-
-        # iterate files
-        for name in files:
-            # get source file path
-            src_file: str = os.path.join(root, name)
-            # check whether copy it
-            if not is_need_copy(src_file):
-                continue
-            # build dst path and copy it
-            dst_file: str = relative_to_folder(src_file, from_folder, to_folder)
-            print(f'Copying: {src_file} -> {dst_file}')
-            shutil.copy(src_file, dst_file)
-
-        # iterate folders when recursively flag enabled
-        # if recursively:
-        #     for name in dirs:
-        #         # get source folder path
-        #         src_folder: str = os.path.join(root, name)
-        #         # build dst path and create it
-        #         dst_folder: str = relative_to_folder(src_folder, from_folder, to_folder)
-        #         print(f'Copying: {src_folder} -> {dst_folder}')
-        #         os.makedirs(dst_folder, exist_ok=True)
-
-        # if we don't have recursively flag, 
-        # we should exit at the end of first loop
-        if not recursively:
-            break
-
diff --git a/bbp_ng/tools/redist.py b/bbp_ng/tools/redist.py
diff --git a/docs/docs/imgs/config-plugin.png b/docs/docs/imgs/config-plugin.png
diff --git a/docs/docs/zh-cn/compile-distribute-plugin.md b/docs/docs/zh-cn/compile-distribute-plugin.md
@@ -20,7 +20,11 @@ BBP内置了一系列自定义图标，以及其组件BME需要的用于描述
 
 ## 打包
 
-将`bbp_ng`文件夹压缩成ZIP文件即可完成打包工作。需要注意的是下列文件或文件夹不应被打包：
+从Blender 4.2 LTS开始，插件使用Blender自带的打包功能进行打包。
+
+假定在项目根目录下执行命令，最终输出文件为`redist/bbp_ng.zip`，那么在命令行窗口中执行`blender --command extension build --source-dir bbp_ng --output-filepath redist/bbp_ng.zip`命令即可完成打包。其中`blender`为Blender的可执行程序。
+
+Blender会根据`blender_manifest.toml`的指示，在排除下列文件的情况下将插件打包：
 
 * `bbp_ng/raw_icons`：原始图片文件夹。
 * `bbp_ng/raw_jsons`：原始JSON文件夹。
@@ -30,10 +34,6 @@ BBP内置了一系列自定义图标，以及其组件BME需要的用于描述
 * `bbp_ng/icons/.gitkeep`：文件夹占位符
 * `bbp_ng/jsons/.gitkeep`：文件夹占位符
 
-打包后的ZIP文件打开后如果有且只有`bbp_ng`一个文件夹，则代表打包成功。切勿直接将`bbp_ng` **内部的文件** 直接打包到ZIP文件中。
-
-这样打包后的ZIP文件既可以直接通过Blender插件的安装功能直接安装，也可以解压在插件目录下完成安装。
-
 ## 生成帮助文档
 
 虽然本项目会利用GitHub Page功能提供帮助文档，但有时你可能需要提供帮助文档的离线版本，本节将会介绍如何生成离线版本的帮助文档。

diff --git a/docs/docs/zh-cn/configure-plugin.md b/docs/docs/zh-cn/configure-plugin.md
@@ -7,7 +7,7 @@
 
 ## 打开配置面板
 
-开启Blender，选择`Edit - Preferences`，在打开的窗口中转到`Add-ons`选项卡，在`Community`分类下找到BBP插件，名称为`Object: Ballance Blender Plugin`。请确保其左侧的勾已被选中，代表插件已被启用。点击勾左侧的三角箭头展开插件详细信息，如图所示，进入配置面板。
+开启Blender，选择`Edit - Preferences`，在打开的窗口中转到`Add-ons`选项卡，在列表中找到BBP插件，其名称为`Ballance Blender Plugin`。请确保其左侧的勾已被选中，代表插件已被启用。点击勾左侧的三角箭头展开插件详细信息，如图所示，进入配置面板。
 
 ![](../imgs/config-plugin.png)
 

diff --git a/docs/docs/zh-cn/install-plugin.md b/docs/docs/zh-cn/install-plugin.md
@@ -2,26 +2,36 @@
 
 ## 明确版本
 
-BBP对Blender支持的原则是支持当前最新的 **LTS** 版本，在最新的LTS版本释出之后会花一些时间迁移插件。当前插件版本 **4.0**，基于Blender **3.6.x** 版本。
+BBP对Blender支持的原则是支持当前最新的 **LTS** 版本，在最新的LTS版本释出之后会花一些时间迁移插件。当前插件版本 **4.0**，基于Blender **4.2.x** 版本。
 
-理论上而言，如果Blender没有做出重大改动，那么BBP可以在其它版本上正常运行。例如你可以尝试在Blender 4.0上运行基于Blender 3.6的BBP插件。但BBP的开发者不会处理仅在非LTS版本中才出现的Bug。在安装插件之前，请先选择适合的版本。
+理论上而言，如果Blender没有做出重大改动，那么BBP可以在其它版本上正常运行。例如你可以尝试在Blender 4.0上运行基于Blender 3.6 LTS的BBP插件。但BBP的开发者不会处理仅在非LTS版本中才出现的Bug。在安装插件之前，请先选择适合的版本。
 
 ## 卸载旧插件
 
 如果你之前使用过BBP，那么你需要首先卸载它。旧版的BBP通常被安装在下列的位置中：
 
-* `Blender/3.6/scripts/addons/ballance_blender_plugin`
-* `Blender/3.6/scripts/addons_contrib/ballance_blender_plugin`
-* `Blender/3.6/scripts/addons/bbp_ng`
+* `<Blender>/3.6/scripts/addons/ballance_blender_plugin`：BBP 3.0或更低版本
+* `<Blender>/3.6/scripts/addons_contrib/ballance_blender_plugin`：BBP 3.0或更低版本
+* `<Blender>/3.6/scripts/addons/bbp_ng`：BBP 4.0内测版本
+* `%APPDATA%/Blender Foundation/Blender/3.6/scripts/addons/bbp_ng`：BBP 4.0内测版本
+* `%APPDATA%/Blender Foundation/Blender/4.2/extensions/user_default/bbp_ng`：BBP 4.0或更高版本
 
-你只需要删除这些文件夹（如果它们存在的话）即可完全卸载插件。路径中的`Blender`指代你的Blender安装位置。路径中的`3.6`是你安装的Blender的版本号，需要根据你安装的版本进行调整，本手册均以`3.6`为例。
+你只需要先在Blender中关闭插件（把插件名前面的勾取消），然后再删除这些文件夹（如果它们存在的话）即可完全卸载插件。路径中的`<Blender>`指代你的Blender安装位置。路径中的`3.6`和`4.2`是你安装的Blender的版本号，需要根据你安装的版本进行调整，后续出现的版本号也按此理解。
+
+!!! warning "不能使用Blender的插件卸载功能"
+    不能使用Blender插件页面的插件卸载功能卸载BBP，因为BBP只要被Blender加载（无论是否启用），都会将Virtools文件读写库BMap加载进Blender。若在Blender运行期间删除，会出现拒绝访问错误。因此您必须在关闭Blender后手动删除插件目录。
+
+    如果您实在无法确定插件安装到了哪里，可以在Blender的偏好设置中的插件页面里找到`File`属性，其指向文件所在的文件夹就是要删除的文件夹。
 
 !!! info "`ballance_blender_plugin`和`bbp_ng`"
     `ballance_blender_plugin`是旧版BBP插件（4.0版本前）的模块名，`bbp_ng`是新版BBP插件（4.0版本后，包括4.0版本）的模块名。为了保证用户确实删除了旧版插件，所以同时提供了这两者。
 
 !!! info "`addons`和`addons_contrib`"
     在Blender 3.6 LTS版本，即BBP 3.3版本之后，Blender不再支持Testing类型插件。因而导致安装Testing插件专用的`addons_contrib`文件夹不再使用，插件需要被统一安装在`addons`中。为了保证用户确实删除了旧版插件，所以同时提供了这两者。
 
+!!! info "`addons`和`extensions`"
+    在Blender 4.2 LTS版本，Blender使用扩展（Extensions）而非插件（Addons）来描述插件。因而导致安装插件的位置也发生了变化。为了保证用户确实删除了旧版插件，所以同时提供了这两者。
+
 ## 下载插件
 
 你可以通过[本工程的GitHub代码库的Release页面](https://github.com/yyc12345/BallanceBlenderHelper/releases)下载最新的插件。插件是以ZIP压缩包形式提供的。
@@ -36,11 +46,11 @@ BBP对Blender支持的原则是支持当前最新的 **LTS** 版本，在最新
 
 ## 安装插件
 
-开启Blender，选择`Edit - Preferences`，在打开的窗口中转到`Add-ons`选项卡，点击`Install...`按钮，选择刚刚下载完毕的ZIP压缩包，即可安装完成。若没有在列表中看到可选择刷新按钮或重启Blender。
+开启Blender，选择`Edit - Preferences`，在打开的窗口中转到`Add-ons`选项卡，点击窗口右上方的箭头，然后点击`Install from Disk...`按钮，选择刚刚下载完毕的ZIP压缩包，即可安装完成。若没有在列表中看到可选择刷新按钮或重启Blender。
 
-你也可以选择手动安装插件（如果上述安装方法失败了的话），转到`Blender/3.6/scripts/addons`，将下载好的ZIP压缩包内容解压到此文件夹下，启动Blender，即可在插件列表中找到BBP。
+你也可以选择手动安装插件（如果上述安装方法失败了的话），转到`%APPDATA%/Blender Foundation/Blender/4.2/extensions/user_default`，创建一个名为`bbp_ng`的文件夹并进入，将下载好的ZIP压缩包内容解压到此文件夹下，启动Blender，即可在插件列表中找到BBP。
 
-BBP插件位于`Community`类别下，名称为`Object: Ballance Blender Plugin`，找到后勾选名称左侧的勾即可启用插件。插件安装成功后的偏好设置页面如下图所示。
+BBP插件在列表中的名称为`Ballance Blender Plugin`，找到后勾选名称左侧的勾即可启用插件。插件安装成功后的偏好设置页面如下图所示。
 
 ![](../imgs/config-plugin.png)