diff --git a/bbp_ng/blender_manifest.toml b/bbp_ng/blender_manifest.toml index dc82f1a..b88b00b 100644 --- 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 " # 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" -# ] \ No newline at end of file +# "./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. +] \ No newline at end of file diff --git a/bbp_ng/tools/common.py b/bbp_ng/tools/common.py index 00b7490..d189d95 100644 --- 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 deleted file mode 100644 index 564dd17..0000000 --- a/bbp_ng/tools/redist.py +++ /dev/null @@ -1,66 +0,0 @@ -import os, argparse, shutil -import common - -def create_redist(redist_folder: str) -> None: - # get plugin root folder and redist folder - root_folder: str = common.get_plugin_folder() - - # we do not want to use script to recursively delete any folder - # because we are afraid of accident `rm -rf /*` disaster. - # but we still need a empty folder to copy file, - # so we check whether redist folder is existing and hope user manually clean it. - redist_folder = os.path.abspath(redist_folder) - if os.path.exists(redist_folder): - print(f'"{redist_folder}" is already existing. This may cause problem, please empty it first before running redist script.') - # make sure redist folder is existing. - os.makedirs(redist_folder, exist_ok=True) - - # copy core python files - common.conditional_file_copy( - root_folder, - redist_folder, - ('*.py', '*.toml', ), - None, - False - ) - - # copy jsons - common.conditional_file_copy( - os.path.join(root_folder, 'jsons'), - os.path.join(redist_folder, 'jsons'), - ('*.json', ), - None, - False - ) - # copy icons - common.conditional_file_copy( - os.path.join(root_folder, 'icons'), - os.path.join(redist_folder, 'icons'), - ('*.png', ), - None, - True - ) - # copy meshes - common.conditional_file_copy( - os.path.join(root_folder, 'meshes'), - os.path.join(redist_folder, 'meshes'), - ('*.bin', ), - None, - False - ) - # copy BMap library - common.conditional_file_copy( - os.path.join(root_folder, 'PyBMap'), - os.path.join(redist_folder, 'PyBMap'), - ('*.py', '*.dll', '*.so', '*.dylib', '*.bin', '*.pdb', ), - None, - False - ) - - print('Done.') - -if __name__ == '__main__': - parser = argparse.ArgumentParser(description='BBP NG Redist Script') - parser.add_argument('-o', '--output', required=True, action='store', dest='output', help='The path to redist folder.') - args = parser.parse_args() - create_redist(args.output) diff --git a/docs/docs/imgs/config-plugin.png b/docs/docs/imgs/config-plugin.png index 14f15ba..43efaed 100644 Binary files a/docs/docs/imgs/config-plugin.png and b/docs/docs/imgs/config-plugin.png differ diff --git a/docs/docs/zh-cn/compile-distribute-plugin.md b/docs/docs/zh-cn/compile-distribute-plugin.md index 81311b4..4036e2b 100644 --- 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 index 017d4a0..eeac049 100644 --- 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 index 1854b66..580cd41 100644 --- a/docs/docs/zh-cn/install-plugin.md +++ b/docs/docs/zh-cn/install-plugin.md @@ -2,19 +2,26 @@ ## 明确版本 -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` +* `/3.6/scripts/addons/ballance_blender_plugin`：BBP 3.0或更低版本 +* `/3.6/scripts/addons_contrib/ballance_blender_plugin`：BBP 3.0或更低版本 +* `/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安装位置。路径中的`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版本）的模块名。为了保证用户确实删除了旧版插件，所以同时提供了这两者。 @@ -22,6 +29,9 @@ BBP对Blender支持的原则是支持当前最新的 **LTS** 版本，在最新 !!! 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)