i18n: update translation

- bump up version to 4.2
- update document about translation.

.gitattributes

@@ -0,0 +1,7 @@
+# all png are binary
+*.png binary
+# our generated mesh should be save as binary
+*.bin binary
+# the raw json data should be binary
+# although i edit it manually
+bbp_ng/raw_jsons/*.json    binary

.github/workflows/main.yml

@@ -0,0 +1,27 @@
+name: Publish docs via GitHub Pages
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  build:
+    name: Deploy docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout master
+        uses: actions/checkout@v4
+        with:
+          ref: master
+  
+      - name: Install MkDocs
+        run: |
+          echo 'mkdocs' > requirements.txt
+          echo 'pymdown-extensions' >> requirements.txt
+
+      - name: Deploy docs
+        uses: mhausenblas/mkdocs-deploy-gh-pages@nomaterial
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          CONFIG_FILE: docs/mkdocs.yml
+          # GITHUB_DOMAIN: github.myenterprise.com

.gitignore

@@ -1,138 +1,3 @@
-# Byte-compiled / optimized / DLL files
-__pycache__/
-*.py[cod]
-*$py.class
-
-# C extensions
-*.so
-
-# Distribution / packaging
-.Python
-build/
-develop-eggs/
-dist/
-downloads/
-eggs/
-.eggs/
-lib/
-lib64/
-parts/
-sdist/
-var/
-wheels/
-share/python-wheels/
-*.egg-info/
-.installed.cfg
-*.egg
-MANIFEST
-
-# PyInstaller
-#  Usually these files are written by a python script from a template
-#  before PyInstaller builds the exe, so as to inject date/other infos into it.
-*.manifest
-*.spec
-
-# Installer logs
-pip-log.txt
-pip-delete-this-directory.txt
-
-# Unit test / coverage reports
-htmlcov/
-.tox/
-.nox/
-.coverage
-.coverage.*
-.cache
-nosetests.xml
-coverage.xml
-*.cover
-*.py,cover
-.hypothesis/
-.pytest_cache/
-cover/
-
-# Translations
-*.mo
-*.pot
-
-# Django stuff:
-*.log
-local_settings.py
-db.sqlite3
-db.sqlite3-journal
-
-# Flask stuff:
-instance/
-.webassets-cache
-
-# Scrapy stuff:
-.scrapy
-
-# Sphinx documentation
-docs/_build/
-
-# PyBuilder
-.pybuilder/
-target/
-
-# Jupyter Notebook
-.ipynb_checkpoints
-
-# IPython
-profile_default/
-ipython_config.py
-
-# pyenv
-#   For a library or package, you might want to ignore these files since the code is
-#   intended to run in multiple environments; otherwise, check them in:
-# .python-version
-
-# pipenv
-#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
-#   However, in case of collaboration, if having platform-specific dependencies or dependencies
-#   having no cross-platform support, pipenv may install dependencies that don't work, or not
-#   install all needed dependencies.
-#Pipfile.lock
-
-# PEP 582; used by e.g. github.com/David-OConnor/pyflow
-__pypackages__/
-
-# Celery stuff
-celerybeat-schedule
-celerybeat.pid
-
-# SageMath parsed files
-*.sage.py
-
-# Environments
-.env
-.venv
-env/
-venv/
-ENV/
-env.bak/
-venv.bak/
-
-# Spyder project settings
-.spyderproject
-.spyproject
-
-# Rope project settings
-.ropeproject
-
-# mkdocs documentation
-/site
-
-# mypy
-.mypy_cache/
-.dmypy.json
-dmypy.json
-
-# Pyre type checker
-.pyre/
-
-# pytype static type analyzer
-.pytype/
-
-# Cython debug symbols
-cython_debug/
+## ===== Personal =====
+# Disable distribution build folder
+redist/

README.md

@@ -1,9 +1,7 @@
-# Ballance Blender Helper
+# BBP NG
 
-This is a Blender plugin which is served for Ballance mapping.
+[中文版本](README_ZH.md)
 
-WIP. Only BM export function is finished. But it is enough. Following function will be added in the future and it just like the decoration of BM export. Because once we have BM export, every map can be converted from Blender to Virtools.
+BBP NG, abbr **B**allance **B**lender **P**lugin **N**ext **G**eneration.
 
-BM file spec can be seen in [there](https://github.com/yyc12345/gist/tree/master/BMFileSpec)
-
-Support criteria: Only support the lastest **LTS** version.
+For an introduction to this plugin, installing it, compiling it, reporting bugs, etc., see the GitHub Page of this project: https://yyc12345.github.io/BallanceBlenderHelper

README_ZH.md

@@ -0,0 +1,7 @@
+# BBP NG
+
+[English version](README.md)
+
+BBP NG，又名**B**allance **B**lender **P**lugin **N**ext **G**eneration（下一代Ballance Blender插件）。
+
+有关此插件的介绍，安装，编译，汇报错误等，请参阅本项目的GitHub Page页面：https://yyc12345.github.io/BallanceBlenderHelper

ballance_blender_plugin/__init__.py

@@ -1,134 +0,0 @@
-bl_info={
-	"name":"Ballance Blender Plugin",
-	"description":"Ballance mapping tools for Blender",
-	"author":"yyc12345",
-	"version":(0,1),
-	"blender":(2,83,0),
-	"category":"Object",
-	"support":"TESTING"
-}
-
-# ============================================= import system
-import bpy,bpy_extras
-# import my code (with reload)
-if "bpy" in locals():
-    import importlib
-    if "bm_import_export" in locals():
-        importlib.reload(bm_import_export)
-    if "floor_rail_uv" in locals():
-        importlib.reload(floor_rail_uv)
-    if "utils" in locals():
-        importlib.reload(utils)
-    if "config" in locals():
-        importlib.reload(config)
-from . import config, utils, bm_import_export, floor_rail_uv
-
-# ============================================= func block
-
-class ImportBM(bpy.types.Operator, bpy_extras.io_utils.ImportHelper):
-    """Load a Ballance Map File"""
-    bl_idname = "import_scene.bm"
-    bl_label = "Import BM"
-    bl_options = {'PRESET', 'UNDO'}
-    filename_ext = ".bm"
-
-    def execute(self, context):
-        bm_import_export.import_bm(context, self.filepath)
-        return {'FINISHED'}
-        
-class ExportBM(bpy.types.Operator, bpy_extras.io_utils.ExportHelper):
-    """Save a Ballance Map File"""
-    bl_idname = "export_scene.bm"
-    bl_label = 'Export BM'
-    bl_options = {'PRESET'}
-    filename_ext = ".bm"
-    
-    export_mode: bpy.props.EnumProperty(
-        name="Export mode",
-        items=(('COLLECTION', "Selected collection", "Export the selected collection"),
-               ('OBJECT', "Selected objects", "Export the selected objects"),
-               ),
-        )
-    export_target: bpy.props.StringProperty(
-        name="Export target",
-        description="Which one will be exported",
-        )
-    no_component_suffix: bpy.props.StringProperty(
-        name="No component suffix",
-        description="The object which have this suffix will not be saved as component.",
-        )
-    
-    def execute(self, context):
-        bm_import_export.export_bm(context, self.filepath, self.export_mode, self.export_target, self.no_component_suffix)
-        return {'FINISHED'}
-
-# ============================================= menu system
-
-class RailUVOperator(bpy.types.Operator):
-    """Create a UV for rail"""
-    bl_idname = "ballance.rail_uv"
-    bl_label = "Create Rail UV"
-    bl_options = {'UNDO'}
-
-    def execute(self, context):
-        floor_rail_uv.create_rail_uv()
-        return {'FINISHED'}
-
-class FloorUVOperator(bpy.types.Operator):
-    """Virtoolize the UV of floor"""
-    bl_idname = "ballance.floor_uv"
-    bl_label = "Virtoolize floor UV"
-    bl_options = {'UNDO'}
-
-    def execute(self, context):
-        floor_rail_uv.virtoolize_floor_uv()
-        return {'FINISHED'}
-
-class ThreeDViewerMenu(bpy.types.Menu):
-    bl_label = "Ballance 3D"
-    bl_idname = "OBJECT_MT_ballance3d_menu"
-
-    def draw(self, context):
-        layout = self.layout
-
-        layout.operator("ballance.rail_uv")
-        layout.operator("ballance.floor_uv")
-
-# ============================================= blender call system
-
-classes = (
-    ImportBM,
-    ExportBM,
-    RailUVOperator,
-    FloorUVOperator,
-    ThreeDViewerMenu
-)
-
-def menu_func_bm_import(self, context):
-    self.layout.operator(ImportBM.bl_idname, text="Ballance Map (.bm)")
-def menu_func_bm_export(self, context):
-    self.layout.operator(ExportBM.bl_idname, text="Ballance Map (.bm)")
-def menu_func_ballance_3d(self, context):
-    layout = self.layout
-    layout.menu(ThreeDViewerMenu.bl_idname)
-
-def register():
-    for cls in classes:
-        bpy.utils.register_class(cls)
-        
-    bpy.types.TOPBAR_MT_file_import.append(menu_func_bm_import)
-    bpy.types.TOPBAR_MT_file_export.append(menu_func_bm_export)
-
-    bpy.types.VIEW3D_HT_header.append(menu_func_ballance_3d)
-        
-def unregister():
-    bpy.types.TOPBAR_MT_file_import.remove(menu_func_bm_import)
-    bpy.types.TOPBAR_MT_file_export.remove(menu_func_bm_export)
-    
-    bpy.types.VIEW3D_HT_header.remove(menu_func_ballance_3d)
-
-    for cls in classes:
-        bpy.utils.unregister_class(cls)
-    
-if __name__=="__main__":
-	register()

ballance_blender_plugin/bm_import_export.py

@@ -1,328 +0,0 @@
-import bpy,bmesh,bpy_extras,mathutils
-import pathlib,zipfile,time,os,tempfile,math
-import struct,shutil
-from bpy_extras import io_utils,node_shader_utils
-from . import utils, config
-
-bm_current_version = 10
-
-def import_bm(context,filepath):
-    # todo: finish this
-    pass
-    
-def export_bm(context,filepath,export_mode, export_target, no_component_suffix):
-    # ============================================ alloc a temp folder
-    tempFolderObj = tempfile.TemporaryDirectory()
-    tempFolder = tempFolderObj.name
-    # debug
-    # tempFolder = "G:\\ziptest"
-    tempTextureFolder = os.path.join(tempFolder, "Texture")
-    os.makedirs(tempTextureFolder)
-    
-    # ============================================ find export target
-    if export_mode== "COLLECTION":
-        objectList = bpy.data.collections[export_target].objects
-    else:
-        objectList = [bpy.data.objects[export_target]]
-
-    needSuffixChecker = no_component_suffix != ""
-    componentObj = set()
-    for obj in objectList:
-        if needSuffixChecker and obj.name.endwith(no_component_suffix):
-            pass # meshObjList.add(obj)
-        else:
-            if is_component(obj.name):
-                componentObj.add(obj)
-            else:
-                pass # meshObjList.add(obj)
-                    
-    # ============================================ export
-    finfo = open(os.path.join(tempFolder, "index.bm"), "wb")
-    finfo.write(struct.pack("I", bm_current_version))
-    
-    # ====================== export object
-    fobject = open(os.path.join(tempFolder, "object.bm"), "wb")
-    meshSet = set()
-    meshList = []
-    meshCount = 0
-    for obj in objectList:
-        # only export mesh object
-        if obj.type != 'MESH':
-            continue
-        
-        varis_component = obj in componentObj
-
-        # clean no mesh object
-        currentMesh = obj.data
-        if currentMesh == None:
-            continue
-        # triangle first and then group
-        if not varis_component:
-            if currentMesh not in meshSet:
-                mesh_triangulate(currentMesh)
-                meshSet.add(currentMesh)
-                meshList.append(currentMesh)
-                meshId = meshCount
-                meshCount += 1
-            else:
-                meshId = meshList.index(currentMesh)
-
-        # write finfo first
-        write_string(finfo, obj.name)
-        write_int(finfo, info_bm_type.OBJECT)
-        write_long(finfo, fobject.tell())
-
-        # write fobject
-        write_int(fobject, 1 if varis_component else 0)
-        write_worldMatrix(fobject, obj.matrix_world)
-        if varis_component:
-            write_int(fobject, get_component_id(obj.name))
-        else:
-            write_int(fobject, meshId)
-
-    fobject.close()
-
-    # ====================== export mesh
-    fmesh = open(os.path.join(tempFolder, "mesh.bm"), "wb")
-    materialSet = set()
-    materialList = []
-    for mesh in meshList:
-        mesh.calc_normals_split()
-
-        # write finfo first
-        write_string(finfo, mesh.name)
-        write_int(finfo, info_bm_type.MESH)
-        write_long(finfo, fmesh.tell())
-
-        # write fmesh
-        # vertices
-        vecList = mesh.vertices[:]
-        write_int(fmesh, len(vecList))
-        for vec in vecList:
-            #swap yz
-            write_3vector(fmesh,vec.co[0],vec.co[2],vec.co[1])
-
-        # uv
-        face_index_pairs = [(face, index) for index, face in enumerate(mesh.polygons)]
-        uv_layer = mesh.uv_layers.active.data[:]
-        write_int(fmesh, len(face_index_pairs) * 3)
-        for f, f_index in face_index_pairs:
-            # it should be triangle face, otherwise throw a error
-            if (f.loop_total != 3):
-                raise Exception("Not a triangle", f.poly.loop_total)
-
-            for loop_index in range(f.loop_start, f.loop_start + f.loop_total):
-                uv = uv_layer[loop_index].uv
-                # reverse v
-                write_2vector(fmesh, uv[0], -uv[1])
-
-        # normals
-        write_int(fmesh, len(face_index_pairs) * 3)
-        for f, f_index in face_index_pairs:
-            # no need to check triangle again
-            for loop_index in range(f.loop_start, f.loop_start + f.loop_total):
-                nml = mesh.loops[loop_index].normal
-                # swap yz
-                write_3vector(fmesh, nml[0], nml[2], nml[1])
-
-        # face
-        # get material first
-        currentMat = mesh.materials[:]
-        noMaterial = len(currentMat) == 0
-        for mat in currentMat:
-            if mat not in materialSet:
-                materialSet.add(mat)
-                materialList.append(mat)
-
-        write_int(fmesh, len(face_index_pairs))
-        vtIndex = []
-        vnIndex = []
-        vIndex = []
-        for f, f_index in face_index_pairs:
-            # confirm material use
-            if noMaterial:
-                usedMat = 0
-            else:
-                usedMat = materialList.index(currentMat[f.material_index])
-
-            # export face
-            vtIndex.clear()
-            vnIndex.clear()
-            vIndex.clear()
-
-            counter = 0
-            for loop_index in range(f.loop_start, f.loop_start + f.loop_total):
-                vIndex.append(mesh.loops[loop_index].vertex_index)
-                vnIndex.append(f_index * 3 + counter)
-                vtIndex.append(f_index * 3 + counter)
-                counter += 1
-            # reverse vertices sort
-            write_face(fmesh,
-            vIndex[2], vtIndex[2], vnIndex[2],
-            vIndex[1], vtIndex[1], vnIndex[1],
-            vIndex[0], vtIndex[0], vnIndex[0])
-
-            # set used material
-            write_int(fmesh, 0 if noMaterial else 1)
-            write_int(fmesh, usedMat)
-
-        mesh.free_normals_split()
-
-    fmesh.close()
-
-    # ====================== export material
-    fmaterial = open(os.path.join(tempFolder, "material.bm"), "wb")
-    textureSet = set()
-    textureList = []
-    textureCount = 0
-
-    for material in materialList:
-        # write finfo first
-        write_string(finfo, material.name)
-        write_int(finfo, info_bm_type.MATERIAL)
-        write_long(finfo, fmaterial.tell())
-
-        # write basic color
-        mat_wrap = node_shader_utils.PrincipledBSDFWrapper(material)
-        if mat_wrap:
-            use_mirror = mat_wrap.metallic != 0.0
-            if use_mirror:
-                write_3vector(fmaterial, mat_wrap.metallic, mat_wrap.metallic, mat_wrap.metallic)
-            else:
-                write_3vector(fmaterial, 1, 1, 1)
-            write_3vector(fmaterial, mat_wrap.base_color[0], mat_wrap.base_color[1], mat_wrap.base_color[2])
-            write_3vector(fmaterial, mat_wrap.specular, mat_wrap.specular, mat_wrap.specular)
-        
-            # confirm texture
-            tex_wrap = getattr(mat_wrap, "base_color_texture", None)
-            if tex_wrap:
-                image = tex_wrap.image
-                if image:
-                    # add into texture list
-                    if image not in textureSet:
-                        textureSet.add(image)
-                        textureList.append(image)
-                        currentTexture = textureCount
-                        textureCount += 1
-                    else:
-                        currentTexture = textureList.index(image)
-
-                    write_int(fmaterial, 1)
-                    write_int(fmaterial, currentTexture)
-                else:
-                    # no texture
-                    write_int(fmaterial, 0)
-                    write_int(fmaterial, 0)
-            else:
-                # no texture
-                write_int(fmaterial, 0)
-                write_int(fmaterial, 0)
-
-        else:
-            # no Principled BSDF. write garbage
-            write_3vector(fmaterial, 0.8, 0.8, 0.8)
-            write_3vector(fmaterial, 0.8, 0.8, 0.8)
-            write_3vector(fmaterial, 0.8, 0.8, 0.8)
-            write_int(fmaterial, 0)
-            write_int(fmaterial, 0)
-    
-    fmaterial.close()
-
-    # ====================== export texture
-    ftexture = open(os.path.join(tempFolder, "texture.bm"), "wb")
-    source_dir = os.path.dirname(bpy.data.filepath)
-    existed_texture = set()
-    
-    for texture in textureList:
-        # write finfo first
-        write_string(finfo, texture.name)
-        write_int(finfo, info_bm_type.TEXTURE)
-        write_long(finfo, ftexture.tell())
-
-        # confirm internal
-        texture_filepath = io_utils.path_reference(texture.filepath, source_dir, tempTextureFolder,
-                                                       'ABSOLUTE', "", None, texture.library)
-        filename = os.path.basename(texture_filepath)
-        write_string(ftexture, filename)
-        if (is_external_texture(filename)):
-            write_int(ftexture, 1)
-        else:
-            # copy internal texture, if this file is copied, do not copy it again
-            write_int(ftexture, 0)
-            if filename not in existed_texture:
-                shutil.copy(texture_filepath, os.path.join(tempTextureFolder, filename))
-                existed_texture.add(filename)
-
-    ftexture.close()
-
-    # close info fs
-    finfo.close()
-
-    # ============================================ save zip and clean up folder
-    if os.path.isfile(filepath):
-        os.remove(filepath)
-    with zipfile.ZipFile(filepath, 'w', zipfile.ZIP_DEFLATED, 9) as zipObj:
-       for folderName, subfolders, filenames in os.walk(tempFolder):
-           for filename in filenames:
-               filePath = os.path.join(folderName, filename)
-               arcname=os.path.relpath(filePath, tempFolder)
-               zipObj.write(filePath, arcname)
-    tempFolderObj.cleanup()
-
-# ======================================================================================= export / import assistant
-
-class info_bm_type():
-    OBJECT = 0
-    MESH = 1
-    MATERIAL = 2
-    TEXTURE = 3
-
-def is_component(name):
-    return get_component_id(name) != -1
-
-def get_component_id(name):
-    return -1 # todo: finish this, -1 mean not a component
-
-def is_external_texture(name):
-    if name in config.external_texture_list:
-        return True
-    else:
-        return False
-
-def mesh_triangulate(me):
-    bm = bmesh.new()
-    bm.from_mesh(me)
-    bmesh.ops.triangulate(bm, faces=bm.faces)
-    bm.to_mesh(me)
-    bm.free()
-
-# ======================================================================================= file io assistant
-
-def write_string(fs,str):
-    count=len(str)
-    write_int(fs,count)
-    fs.write(str.encode("utf_32_le"))
-
-def write_int(fs,num):
-    fs.write(struct.pack("I", num))
-
-def write_long(fs,num):
-    fs.write(struct.pack("Q", num))
-
-def write_worldMatrix(fs, matt):
-    mat = matt.transposed()
-    fs.write(struct.pack("ffffffffffffffff",
-    mat[0][0],mat[0][2], mat[0][1], mat[0][3],
-    mat[2][0],mat[2][2], mat[2][1], mat[2][3],
-    mat[1][0],mat[1][2], mat[1][1], mat[1][3],
-    mat[3][0],mat[3][2], mat[3][1], mat[3][3]))
-
-def write_3vector(fs, x, y ,z):
-    fs.write(struct.pack("fff", x, y ,z))
-
-def write_2vector(fs, u, v):
-    fs.write(struct.pack("ff", u, v))
-
-def write_face(fs, v1, vn1, vt1, v2, vn2, vt2, v3, vn3, vt3):
-    fs.write(struct.pack("IIIIIIIII", v1, vn1, vt1, v2, vn2, vt2, v3, vn3, vt3))
-

ballance_blender_plugin/config.py

@@ -1,85 +0,0 @@
-external_texture_list = set([
-    'Ball_LightningSphere1.bmp',
-    'Ball_LightningSphere2.bmp',
-    'Ball_LightningSphere3.bmp',
-    'Ball_Paper.bmp',
-    'Ball_Stone.bmp',
-    'Ball_Wood.bmp',
-    'Brick.bmp',
-    'Button01_deselect.tga',
-    'Button01_select.tga',
-    'Button01_special.tga',
-    'Column_beige.bmp',
-    'Column_beige_fade.tga',
-    'Column_blue.bmp',
-    'Cursor.tga',
-    'Dome.bmp',
-    'DomeEnvironment.bmp',
-    'DomeShadow.tga',
-    'ExtraBall.bmp',
-    'ExtraParticle.bmp',
-    'E_Holzbeschlag.bmp',
-    'FloorGlow.bmp',
-    'Floor_Side.bmp',
-    'Floor_Top_Border.bmp',
-    'Floor_Top_Borderless.bmp',
-    'Floor_Top_Checkpoint.bmp',
-    'Floor_Top_Flat.bmp',
-    'Floor_Top_Profil.bmp',
-    'Floor_Top_ProfilFlat.bmp',
-    'Font_1.tga',
-    'Gravitylogo_intro.bmp',
-    'HardShadow.bmp',
-    'Laterne_Glas.bmp',
-    'Laterne_Schatten.tga',
-    'Laterne_Verlauf.tga',
-    'Logo.bmp',
-    'Metal_stained.bmp',
-    'Misc_Ufo.bmp',
-    'Misc_UFO_Flash.bmp',
-    'Modul03_Floor.bmp',
-    'Modul03_Wall.bmp',
-    'Modul11_13_Wood.bmp',
-    'Modul11_Wood.bmp',
-    'Modul15.bmp',
-    'Modul16.bmp',
-    'Modul18.bmp',
-    'Modul18_Gitter.tga',
-    'Modul30_d_Seiten.bmp',
-    'Particle_Flames.bmp',
-    'Particle_Smoke.bmp',
-    'PE_Bal_balloons.bmp',
-    'PE_Bal_platform.bmp',
-    'PE_Ufo_env.bmp',
-    'Pfeil.tga',
-    'P_Extra_Life_Oil.bmp',
-    'P_Extra_Life_Particle.bmp',
-    'P_Extra_Life_Shadow.bmp',
-    'Rail_Environment.bmp',
-    'sandsack.bmp',
-    'SkyLayer.bmp',
-    'Sky_Vortex.bmp',
-    'Stick_Bottom.tga',
-    'Stick_Stripes.bmp',
-    'Target.bmp',
-    'Tower_Roof.bmp',
-    'Trafo_Environment.bmp',
-    'Trafo_FlashField.bmp',
-    'Trafo_Shadow_Big.tga',
-    'Tut_Pfeil01.tga',
-    'Tut_Pfeil_Hoch.tga',
-    'Wolken_intro.tga',
-    'Wood_Metal.bmp',
-    'Wood_MetalStripes.bmp',
-    'Wood_Misc.bmp',
-    'Wood_Nailed.bmp',
-    'Wood_Old.bmp',
-    'Wood_Panel.bmp',
-    'Wood_Plain.bmp',
-    'Wood_Plain2.bmp',
-    'Wood_Raft.bmp'
-])
-
-component_list = [
-    
-]

ballance_blender_plugin/floor_rail_uv.py

@@ -1,34 +0,0 @@
-import bpy,bmesh
-from . import utils
-
-def create_rail_uv():
-    meshList = []
-    for obj in bpy.context.selected_objects:
-        if obj.type != 'MESH':
-            continue
-
-        if obj.data.uv_layers.active.data == None:
-            utils.ShowMessageBox("You should create a UV layer for this object firstly. Then execute this operator.", "No UV layer", 'ERROR')
-            return
-        
-        meshList.append(obj.data)
-    
-    for mesh in meshList:
-        # vecList = mesh.vertices[:]
-        uv_layer = mesh.uv_layers.active.data
-        for poly in mesh.polygons:
-            for loop_index in range(poly.loop_start, poly.loop_start + poly.loop_total):
-                # index = mesh.loops[loop_index].vertex_index
-                uv_layer[loop_index].uv[0] = 0 # vecList[index].co[0]
-                uv_layer[loop_index].uv[1] = 1 # vecList[index].co[1]
-
-
-def virtoolize_floor_uv():
-    pass
-
-def mesh_triangulate(me):
-    bm = bmesh.new()
-    bm.from_mesh(me)
-    bmesh.ops.triangulate(bm, faces=bm.faces)
-    bm.to_mesh(me)
-    bm.free()

ballance_blender_plugin/utils.py

@@ -1,8 +0,0 @@
-import bpy
-
-def ShowMessageBox(message = "", title = "Message Box", icon = 'INFO'):
-
-    def draw(self, context):
-        self.layout.label(text=message)
-
-    bpy.context.window_manager.popup_menu(draw, title = title, icon = icon)

bbp_ng/.gitignore

@@ -0,0 +1,157 @@
+## ===== Personal =====
+# Do not include PyBMap in this repository.
+# Order build fetch it manually.
+PyBMap/
+
+# Disable generated icons and jsons but keep the directory hierarchy.
+icons/*
+!icons/.gitkeep
+jsons/*
+!jsons/.gitkeep
+
+# Do not include intermidiate translation template (POT)
+# NOTE: it seems that Python default gitignore (written following) disable POT file in default.
+# so, as it wish, I also remove it from git.
+i18n/*
+!i18n/blender.pot
+!i18n/*.po
+
+## ===== Python =====
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/

bbp_ng/.style.yapf

@@ -0,0 +1,402 @@
+[style]
+# Align closing bracket with visual indentation.
+align_closing_bracket_with_visual_indent=True
+
+# Allow dictionary keys to exist on multiple lines. For example:
+#
+#   x = {
+#       ('this is the first element of a tuple',
+#        'this is the second element of a tuple'):
+#            value,
+#   }
+allow_multiline_dictionary_keys=False
+
+# Allow lambdas to be formatted on more than one line.
+allow_multiline_lambdas=False
+
+# Allow splitting before a default / named assignment in an argument list.
+allow_split_before_default_or_named_assigns=False
+
+# Allow splits before the dictionary value.
+allow_split_before_dict_value=False
+
+#   Let spacing indicate operator precedence. For example:
+#
+#     a = 1 * 2 + 3 / 4
+#     b = 1 / 2 - 3 * 4
+#     c = (1 + 2) * (3 - 4)
+#     d = (1 - 2) / (3 + 4)
+#     e = 1 * 2 - 3
+#     f = 1 + 2 + 3 + 4
+#
+# will be formatted as follows to indicate precedence:
+#
+#     a = 1*2 + 3/4
+#     b = 1/2 - 3*4
+#     c = (1+2) * (3-4)
+#     d = (1-2) / (3+4)
+#     e = 1*2 - 3
+#     f = 1 + 2 + 3 + 4
+#
+arithmetic_precedence_indication=False
+
+# Number of blank lines surrounding top-level function and class
+# definitions.
+blank_lines_around_top_level_definition=1
+
+# Number of blank lines between top-level imports and variable
+# definitions.
+blank_lines_between_top_level_imports_and_variables=1
+
+# Insert a blank line before a class-level docstring.
+blank_line_before_class_docstring=False
+
+# Insert a blank line before a module docstring.
+blank_line_before_module_docstring=False
+
+# Insert a blank line before a 'def' or 'class' immediately nested
+# within another 'def' or 'class'. For example:
+#
+#   class Foo:
+#                      # <------ this blank line
+#     def method():
+#       pass
+blank_line_before_nested_class_or_def=False
+
+# Do not split consecutive brackets. Only relevant when
+# dedent_closing_brackets is set. For example:
+#
+#    call_func_that_takes_a_dict(
+#        {
+#            'key1': 'value1',
+#            'key2': 'value2',
+#        }
+#    )
+#
+# would reformat to:
+#
+#    call_func_that_takes_a_dict({
+#        'key1': 'value1',
+#        'key2': 'value2',
+#    })
+coalesce_brackets=False
+
+# The column limit.
+column_limit=79
+
+# The style for continuation alignment. Possible values are:
+#
+# - SPACE: Use spaces for continuation alignment. This is default behavior.
+# - FIXED: Use fixed number (CONTINUATION_INDENT_WIDTH) of columns
+#   (ie: CONTINUATION_INDENT_WIDTH/INDENT_WIDTH tabs or
+#   CONTINUATION_INDENT_WIDTH spaces) for continuation alignment.
+# - VALIGN-RIGHT: Vertically align continuation lines to multiple of
+#   INDENT_WIDTH columns. Slightly right (one tab or a few spaces) if
+#   cannot vertically align continuation lines with indent characters.
+continuation_align_style=SPACE
+
+# Indent width used for line continuations.
+continuation_indent_width=4
+
+# Put closing brackets on a separate line, dedented, if the bracketed
+# expression can't fit in a single line. Applies to all kinds of brackets,
+# including function definitions and calls. For example:
+#
+#   config = {
+#       'key1': 'value1',
+#       'key2': 'value2',
+#   }        # <--- this bracket is dedented and on a separate line
+#
+#   time_series = self.remote_client.query_entity_counters(
+#       entity='dev3246.region1',
+#       key='dns.query_latency_tcp',
+#       transform=Transformation.AVERAGE(window=timedelta(seconds=60)),
+#       start_ts=now()-timedelta(days=3),
+#       end_ts=now(),
+#   )        # <--- this bracket is dedented and on a separate line
+dedent_closing_brackets=False
+
+# Disable the heuristic which places each list element on a separate line
+# if the list is comma-terminated.
+disable_ending_comma_heuristic=False
+
+# Place each dictionary entry onto its own line.
+each_dict_entry_on_separate_line=True
+
+# Require multiline dictionary even if it would normally fit on one line.
+# For example:
+#
+#   config = {
+#       'key1': 'value1'
+#   }
+force_multiline_dict=True
+
+# The regex for an i18n comment. The presence of this comment stops
+# reformatting of that line, because the comments are required to be
+# next to the string they translate.
+i18n_comment=
+
+# The i18n function call names. The presence of this function stops
+# reformattting on that line, because the string it has cannot be moved
+# away from the i18n comment.
+i18n_function_call=
+
+# Indent blank lines.
+indent_blank_lines=True
+
+# Put closing brackets on a separate line, indented, if the bracketed
+# expression can't fit in a single line. Applies to all kinds of brackets,
+# including function definitions and calls. For example:
+#
+#   config = {
+#       'key1': 'value1',
+#       'key2': 'value2',
+#       }        # <--- this bracket is indented and on a separate line
+#
+#   time_series = self.remote_client.query_entity_counters(
+#       entity='dev3246.region1',
+#       key='dns.query_latency_tcp',
+#       transform=Transformation.AVERAGE(window=timedelta(seconds=60)),
+#       start_ts=now()-timedelta(days=3),
+#       end_ts=now(),
+#       )        # <--- this bracket is indented and on a separate line
+indent_closing_brackets=False
+
+# Indent the dictionary value if it cannot fit on the same line as the
+# dictionary key. For example:
+#
+#   config = {
+#       'key1':
+#           'value1',
+#       'key2': value1 +
+#               value2,
+#   }
+indent_dictionary_value=False
+
+# The number of columns to use for indentation.
+indent_width=4
+
+# Join short lines into one line. E.g., single line 'if' statements.
+join_multiple_lines=True
+
+# Do not include spaces around selected binary operators. For example:
+#
+#   1 + 2 * 3 - 4 / 5
+#
+# will be formatted as follows when configured with "*,/":
+#
+#   1 + 2*3 - 4/5
+no_spaces_around_selected_binary_operators=
+
+# Use spaces around default or named assigns.
+spaces_around_default_or_named_assign=True
+
+# Adds a space after the opening '{' and before the ending '}' dict
+# delimiters.
+#
+#   {1: 2}
+#
+# will be formatted as:
+#
+#   { 1: 2 }
+spaces_around_dict_delimiters=False
+
+# Adds a space after the opening '[' and before the ending ']' list
+# delimiters.
+#
+#   [1, 2]
+#
+# will be formatted as:
+#
+#   [ 1, 2 ]
+spaces_around_list_delimiters=False
+
+# Use spaces around the power operator.
+spaces_around_power_operator=False
+
+# Use spaces around the subscript / slice operator.  For example:
+#
+#   my_list[1 : 10 : 2]
+spaces_around_subscript_colon=False
+
+# Adds a space after the opening '(' and before the ending ')' tuple
+# delimiters.
+#
+#   (1, 2, 3)
+#
+# will be formatted as:
+#
+#   ( 1, 2, 3 )
+spaces_around_tuple_delimiters=False
+
+# The number of spaces required before a trailing comment.
+# This can be a single value (representing the number of spaces
+# before each trailing comment) or list of values (representing
+# alignment column values; trailing comments within a block will
+# be aligned to the first column value that is greater than the maximum
+# line length within the block). For example:
+#
+# With spaces_before_comment=5:
+#
+#   1 + 1 # Adding values
+#
+# will be formatted as:
+#
+#   1 + 1     # Adding values <-- 5 spaces between the end of the
+#             # statement and comment
+#
+# With spaces_before_comment=15, 20:
+#
+#   1 + 1 # Adding values
+#   two + two # More adding
+#
+#   longer_statement # This is a longer statement
+#   short # This is a shorter statement
+#
+#   a_very_long_statement_that_extends_beyond_the_final_column # Comment
+#   short # This is a shorter statement
+#
+# will be formatted as:
+#
+#   1 + 1          # Adding values <-- end of line comments in block
+#                  # aligned to col 15
+#   two + two      # More adding
+#
+#   longer_statement    # This is a longer statement <-- end of line
+#                       # comments in block aligned to col 20
+#   short               # This is a shorter statement
+#
+#   a_very_long_statement_that_extends_beyond_the_final_column  # Comment <-- the end of line comments are aligned based on the line length
+#   short                                                       # This is a shorter statement
+#
+spaces_before_comment=2
+
+# Insert a space between the ending comma and closing bracket of a list,
+# etc.
+space_between_ending_comma_and_closing_bracket=True
+
+# Use spaces inside brackets, braces, and parentheses.  For example:
+#
+#   method_call( 1 )
+#   my_dict[ 3 ][ 1 ][ get_index( *args, **kwargs ) ]
+#   my_set = { 1, 2, 3 }
+space_inside_brackets=False
+
+# Split before arguments.
+split_all_comma_separated_values=False
+
+# Split before arguments, but do not split all subexpressions recursively
+# (unless needed).
+split_all_top_level_comma_separated_values=False
+
+# Split before arguments if the argument list is terminated by a
+# comma.
+split_arguments_when_comma_terminated=False
+
+# Set to True to prefer splitting before '+', '-', '*', '/', '//', or '@'
+# rather than after.
+split_before_arithmetic_operator=False
+
+# Set to True to prefer splitting before '&', '|' or '^' rather than
+# after.
+split_before_bitwise_operator=True
+
+# Split before the closing bracket if a list or dict literal doesn't fit on
+# a single line.
+split_before_closing_bracket=True
+
+# Split before a dictionary or set generator (comp_for). For example, note
+# the split before the 'for':
+#
+#   foo = {
+#       variable: 'Hello world, have a nice day!'
+#       for variable in bar if variable != 42
+#   }
+split_before_dict_set_generator=True
+
+# Split before the '.' if we need to split a longer expression:
+#
+#   foo = ('This is a really long string: {}, {}, {}, {}'.format(a, b, c, d))
+#
+# would reformat to something like:
+#
+#   foo = ('This is a really long string: {}, {}, {}, {}'
+#          .format(a, b, c, d))
+split_before_dot=False
+
+# Split after the opening paren which surrounds an expression if it doesn't
+# fit on a single line.
+split_before_expression_after_opening_paren=False
+
+# If an argument / parameter list is going to be split, then split before
+# the first argument.
+split_before_first_argument=False
+
+# Set to True to prefer splitting before 'and' or 'or' rather than
+# after.
+split_before_logical_operator=True
+
+# Split named assignments onto individual lines.
+split_before_named_assigns=True
+
+# Set to True to split list comprehensions and generators that have
+# non-trivial expressions and multiple clauses before each of these
+# clauses. For example:
+#
+#   result = [
+#       a_long_var + 100 for a_long_var in xrange(1000)
+#       if a_long_var % 10]
+#
+# would reformat to something like:
+#
+#   result = [
+#       a_long_var + 100
+#       for a_long_var in xrange(1000)
+#       if a_long_var % 10]
+split_complex_comprehension=False
+
+# The penalty for splitting right after the opening bracket.
+split_penalty_after_opening_bracket=300
+
+# The penalty for splitting the line after a unary operator.
+split_penalty_after_unary_operator=10000
+
+# The penalty of splitting the line around the '+', '-', '*', '/', '//',
+# `%`, and '@' operators.
+split_penalty_arithmetic_operator=300
+
+# The penalty for splitting right before an if expression.
+split_penalty_before_if_expr=0
+
+# The penalty of splitting the line around the '&', '|', and '^' operators.
+split_penalty_bitwise_operator=300
+
+# The penalty for splitting a list comprehension or generator
+# expression.
+split_penalty_comprehension=80
+
+# The penalty for characters over the column limit.
+split_penalty_excess_character=7000
+
+# The penalty incurred by adding a line split to the logical line. The
+# more line splits added the higher the penalty.
+split_penalty_for_added_line_split=30
+
+# The penalty of splitting a list of "import as" names. For example:
+#
+#   from a_very_long_or_indented_module_name_yada_yad import (long_argument_1,
+#                                                             long_argument_2,
+#                                                             long_argument_3)
+#
+# would reformat to something like:
+#
+#   from a_very_long_or_indented_module_name_yada_yad import (
+#       long_argument_1, long_argument_2, long_argument_3)
+split_penalty_import_names=0
+
+# The penalty of splitting the line around the 'and' and 'or' operators.
+split_penalty_logical_operator=300
+
+# Use the Tab character for indentation.
+use_tabs=False
+

bbp_ng/OP_ADDS_bme.py

@@ -0,0 +1,316 @@
+import bpy, mathutils
+import typing
+from . import PROP_preferences
+from . import UTIL_functions, UTIL_translation, UTIL_bme
+
+#region BME Adder
+
+_g_EnumHelper_BmeStructType: UTIL_bme.EnumPropHelper = UTIL_bme.EnumPropHelper()
+
+class BBP_PG_bme_adder_cfgs(bpy.types.PropertyGroup):
+    prop_int: bpy.props.IntProperty(
+        name = 'Integral Value', description = 'The field representing a single integral value.',
+        min = 0, max = 64,
+        soft_min = 0, soft_max = 32,
+        step = 1,
+        default = 1,
+        translation_context = 'BBP_PG_bme_adder_cfgs/property'
+    ) # type: ignore
+    prop_float: bpy.props.FloatProperty(
+        name = 'Float Point Value', description = 'The field representing a single float point value.',
+        min = 0.0, max = 1024.0,
+        soft_min = 0.0, soft_max = 512.0,
+        step = 50, # Step is in UI, in [1, 100] (WARNING: actual value is /100). So we choose 50, mean 0.5
+        default = 5.0,
+        translation_context = 'BBP_PG_bme_adder_cfgs/property'
+    ) # type: ignore
+    prop_bool: bpy.props.BoolProperty(
+        name = 'Boolean Value', description = 'The field representing a single boolean value.',
+        default = True,
+        translation_context = 'BBP_PG_bme_adder_cfgs/property'
+    ) # type: ignore
+
+class BBP_OT_add_bme_struct(bpy.types.Operator):
+    """Add BME structure"""
+    bl_idname = "bbp.add_bme_struct"
+    bl_label = "Add BME Structure"
+    bl_options = {'REGISTER', 'UNDO'}
+    bl_translation_context = 'BBP_OT_add_bme_struct'
+    
+    ## There is a compromise due to the shitty Blender design.
+    #  
+    #  The passed `self` of Blender Property update function is not the instance of operator,
+    #  but a simple OperatorProperties.
+    #  It mean that I can not visit the full operator, only what I can do is visit existing 
+    #  Blender properties.
+    #  
+    #  So these is the solution about generating cache list according to the change of bme struct type.
+    #  First, update function will only set a "outdated" flag for operator which is a pre-registered Blender property.
+    #  The "outdated" flags is not showen and not saved.
+    #  Then call a internal cache list update function at the begin of `invoke`, `execute` and `draw`.
+    #  In this internal cache list updator, check "outdated" flag first, if cache is outdated, update and reset flag.
+    #  Otherwise do nothing.
+    #  
+    #  Reference: https://docs.blender.org/api/current/bpy.props.html#update-example
+
+    ## Compromise used "outdated" flag.
+    outdated_flag: bpy.props.BoolProperty(
+        # TR: Property not showen should not have name and desc.
+        # name = "Outdated Type",
+        # description = "Internal flag.",
+        options = {'HIDDEN', 'SKIP_SAVE'},
+        default = False
+    ) # type: ignore
+
+    ## A BME struct cfgs descriptor cache list
+    #  Not only the descriptor self, also the cfg associated index in bme_struct_cfgs
+    bme_struct_cfg_index_cache: list[tuple[UTIL_bme.PrototypeShowcaseCfgDescriptor, int]]
+
+    def __internal_update_bme_struct_type(self) -> None:
+        # if not outdated, skip
+        if not self.outdated_flag: return
+
+        # get available cfg entires
+        cfgs: typing.Iterator[UTIL_bme.PrototypeShowcaseCfgDescriptor]
+        cfgs = _g_EnumHelper_BmeStructType.get_bme_showcase_cfgs(
+            _g_EnumHelper_BmeStructType.get_selection(self.bme_struct_type)
+        )
+
+        # analyse cfgs. 
+        # create counter first
+        counter_int: int = 0
+        counter_float: int = 0
+        counter_bool: int = 0
+        # create cache list
+        self.bme_struct_cfg_index_cache.clear()
+        # iterate cfgs and register them
+        for cfg in cfgs:
+            match(cfg.get_type()):
+                case UTIL_bme.PrototypeShowcaseCfgsTypes.Integer:
+                    self.bme_struct_cfg_index_cache.append((cfg, counter_int))
+                    counter_int += 1
+                case UTIL_bme.PrototypeShowcaseCfgsTypes.Float:
+                    self.bme_struct_cfg_index_cache.append((cfg, counter_float))
+                    counter_float += 1
+                case UTIL_bme.PrototypeShowcaseCfgsTypes.Boolean:
+                    self.bme_struct_cfg_index_cache.append((cfg, counter_bool))
+                    counter_bool += 1
+                case UTIL_bme.PrototypeShowcaseCfgsTypes.Face:
+                    self.bme_struct_cfg_index_cache.append((cfg, counter_bool))
+                    counter_bool += 6   # face will occupy 6 bool.
+
+
+        # init data collection
+        op_cfgs_visitor: UTIL_functions.CollectionVisitor[BBP_PG_bme_adder_cfgs]
+        op_cfgs_visitor = UTIL_functions.CollectionVisitor(self.bme_struct_cfgs)
+        # clear first
+        op_cfgs_visitor.clear()
+        # create enough entries specified by gotten cfgs
+        for _ in range(max(counter_int, counter_float, counter_bool)):
+            op_cfgs_visitor.add()
+
+        # assign default value
+        for (cfg, cfg_index) in self.bme_struct_cfg_index_cache:
+            # show prop differently by cfg type
+            match(cfg.get_type()):
+                case UTIL_bme.PrototypeShowcaseCfgsTypes.Integer:
+                    op_cfgs_visitor[cfg_index].prop_int = cfg.get_default()
+                case UTIL_bme.PrototypeShowcaseCfgsTypes.Float:
+                    op_cfgs_visitor[cfg_index].prop_float = cfg.get_default()
+                case UTIL_bme.PrototypeShowcaseCfgsTypes.Boolean:
+                    op_cfgs_visitor[cfg_index].prop_bool = cfg.get_default()
+                case UTIL_bme.PrototypeShowcaseCfgsTypes.Face:
+                    # face is just 6 bool
+                    default_values: tuple[bool, ...] = cfg.get_default()
+                    for i in range(6):
+                        op_cfgs_visitor[cfg_index + i].prop_bool = default_values[i]
+
+        # reset outdated flag
+        self.outdated_flag = False
+
+    # the updator for default side value
+    def bme_struct_type_updated(self, context):
+        # update outdated flag
+        self.outdated_flag = True
+        # blender required
+        return None
+    
+    bme_struct_type: bpy.props.EnumProperty(
+        name = "Type",
+        description = "The type of BME structure.",
+        items = _g_EnumHelper_BmeStructType.generate_items(),
+        update = bme_struct_type_updated,
+        translation_context = 'BBP_OT_add_bme_struct/property'
+    ) # type: ignore
+    
+    bme_struct_cfgs : bpy.props.CollectionProperty(
+        name = "Configurations",
+        description = "The collection holding BME structure configurations.",
+        type = BBP_PG_bme_adder_cfgs,
+        translation_context = 'BBP_OT_add_bme_struct/property'
+    ) # type: ignore
+    
+    ## Extra transform for good "what you see is what you gotten".
+    #  Extra transform will be added after moving this object to cursor.
+    extra_translation: bpy.props.FloatVectorProperty(
+        name = "Extra Translation",
+        description = "The extra translation applied to object after moving to cursor.",
+        size = 3,
+        subtype = 'TRANSLATION',
+        step = 50, # same step as the float entry of BBP_PG_bme_adder_cfgs
+        default = (0.0, 0.0, 0.0),
+        translation_context = 'BBP_OT_add_bme_struct/property'
+    ) # type: ignore
+    extra_rotation: bpy.props.FloatVectorProperty(
+        name = "Extra Rotation",
+        description = "The extra rotation applied to object after moving to cursor.",
+        size = 3,
+        subtype = 'EULER',
+        step = 100, # We choosen 100, mean 1. Sync with property window.
+        default = (0.0, 0.0, 0.0),
+        translation_context = 'BBP_OT_add_bme_struct/property'
+    ) # type: ignore
+
+    @classmethod
+    def poll(cls, context):
+        return PROP_preferences.get_raw_preferences().has_valid_blc_tex_folder()
+    
+    def invoke(self, context, event):
+        # reset extra transform to identy
+        self.extra_translation = (0.0, 0.0, 0.0)
+        self.extra_rotation = (0.0, 0.0, 0.0)
+        self.extra_scale = (1.0, 1.0, 1.0)
+        # create internal list
+        self.bme_struct_cfg_index_cache = []
+        # trigger default bme struct type updator
+        self.bme_struct_type_updated(context)
+        # call internal updator
+        self.__internal_update_bme_struct_type()
+        # run execute() function
+        return self.execute(context)
+    
+    def execute(self, context):
+        # call internal updator
+        self.__internal_update_bme_struct_type()
+
+        # create cfg visitor
+        op_cfgs_visitor: UTIL_functions.CollectionVisitor[BBP_PG_bme_adder_cfgs]
+        op_cfgs_visitor = UTIL_functions.CollectionVisitor(self.bme_struct_cfgs)
+        # collect cfgs data
+        cfgs: dict[str, typing.Any] = {}
+        for (cfg, cfg_index) in self.bme_struct_cfg_index_cache:
+            match(cfg.get_type()):
+                case UTIL_bme.PrototypeShowcaseCfgsTypes.Integer:
+                    cfgs[cfg.get_field()] = op_cfgs_visitor[cfg_index].prop_int
+                case UTIL_bme.PrototypeShowcaseCfgsTypes.Float:
+                    cfgs[cfg.get_field()] = op_cfgs_visitor[cfg_index].prop_float
+                case UTIL_bme.PrototypeShowcaseCfgsTypes.Boolean:
+                    cfgs[cfg.get_field()] = op_cfgs_visitor[cfg_index].prop_bool
+                case UTIL_bme.PrototypeShowcaseCfgsTypes.Face:
+                    # face is just 6 bool tuple
+                    cfgs[cfg.get_field()] = tuple(
+                        op_cfgs_visitor[cfg_index + i].prop_bool for i in range(6)
+                    )
+
+        # call general creator
+        obj: bpy.types.Object = UTIL_bme.create_bme_struct_wrapper(
+            _g_EnumHelper_BmeStructType.get_selection(self.bme_struct_type),
+            cfgs
+        )
+
+        # add into scene and move to cursor
+        UTIL_functions.add_into_scene_and_move_to_cursor(obj)
+        # add extra transform
+        obj.matrix_world = obj.matrix_world @ mathutils.Matrix.LocRotScale(
+            mathutils.Vector(self.extra_translation),
+            mathutils.Euler(self.extra_rotation, 'XYZ'),
+            mathutils.Vector((1.0, 1.0, 1.0)) # no scale
+        )
+        # select created object
+        UTIL_functions.select_certain_objects((obj, ))
+        return {'FINISHED'}
+    
+    def draw(self, context):
+        # call internal updator
+        self.__internal_update_bme_struct_type()
+
+        # start drawing
+        layout: bpy.types.UILayout = self.layout
+        # show type
+        layout.prop(self, 'bme_struct_type')
+
+        # create cfg visitor
+        op_cfgs_visitor: UTIL_functions.CollectionVisitor[BBP_PG_bme_adder_cfgs]
+        op_cfgs_visitor = UTIL_functions.CollectionVisitor(self.bme_struct_cfgs)
+        # visit cfgs cache list to show cfg
+        layout.label(text="Prototype Configurations", text_ctxt='BBP_OT_add_bme_struct/draw')
+        prototype_cfg_index: int = 0
+        for (cfg, cfg_index) in self.bme_struct_cfg_index_cache:
+            # create box for cfgs
+            box_layout: bpy.types.UILayout = layout.box()
+
+            # draw title and description first
+            # get prototype identifier name and showcase configuration index
+            # then increase the index.
+            prototype_ident: str = _g_EnumHelper_BmeStructType.get_selection(self.bme_struct_type)
+            box_layout.label(text=cfg.get_title(), text_ctxt=UTIL_translation.build_prototype_showcase_cfg_context(prototype_ident, prototype_cfg_index))
+            box_layout.label(text=cfg.get_desc(), text_ctxt=UTIL_translation.build_prototype_showcase_cfg_context(prototype_ident, prototype_cfg_index))
+            prototype_cfg_index += 1
+
+            # show prop differently by cfg type
+            match(cfg.get_type()):
+                case UTIL_bme.PrototypeShowcaseCfgsTypes.Integer:
+                    box_layout.prop(op_cfgs_visitor[cfg_index], 'prop_int', text='')
+                case UTIL_bme.PrototypeShowcaseCfgsTypes.Float:
+                    box_layout.prop(op_cfgs_visitor[cfg_index], 'prop_float', text='')
+                case UTIL_bme.PrototypeShowcaseCfgsTypes.Boolean:
+                    box_layout.prop(op_cfgs_visitor[cfg_index], 'prop_bool', text='')
+                case UTIL_bme.PrototypeShowcaseCfgsTypes.Face:
+                    # face will show a special layout (grid view)
+                    grids = box_layout.grid_flow(
+                        row_major=True, columns=3, even_columns=True, even_rows=True, align=True)
+                    grids.alignment = 'CENTER'
+                    grids.separator()
+                    grids.prop(op_cfgs_visitor[cfg_index + 0], 'prop_bool', text='Top', text_ctxt='BBP_OT_add_bme_struct/draw') # top
+                    grids.prop(op_cfgs_visitor[cfg_index + 2], 'prop_bool', text='Front', text_ctxt='BBP_OT_add_bme_struct/draw') # front
+                    grids.prop(op_cfgs_visitor[cfg_index + 4], 'prop_bool', text='Left', text_ctxt='BBP_OT_add_bme_struct/draw') # left
+                    grids.label(text='', icon='CUBE')   # show a 3d cube as icon
+                    grids.prop(op_cfgs_visitor[cfg_index + 5], 'prop_bool', text='Right', text_ctxt='BBP_OT_add_bme_struct/draw') # right
+                    grids.prop(op_cfgs_visitor[cfg_index + 3], 'prop_bool', text='Back', text_ctxt='BBP_OT_add_bme_struct/draw') # back
+                    grids.prop(op_cfgs_visitor[cfg_index + 1], 'prop_bool', text='Bottom', text_ctxt='BBP_OT_add_bme_struct/draw') # bottom
+                    grids.separator()
+
+        # show extra transform props
+        # forcely order that each one are placed horizontally
+        layout.label(text="Extra Transform", text_ctxt='BBP_OT_add_bme_struct/draw')
+        # translation
+        layout.label(text='Translation', text_ctxt='BBP_OT_add_bme_struct/draw')
+        hbox_layout: bpy.types.UILayout = layout.row()
+        hbox_layout.prop(self, 'extra_translation', text='')
+        # rotation
+        layout.label(text='Rotation', text_ctxt='BBP_OT_add_bme_struct/draw')
+        hbox_layout = layout.row()
+        hbox_layout.prop(self, 'extra_rotation', text='')
+
+    @classmethod
+    def draw_blc_menu(cls, layout: bpy.types.UILayout):
+        for ident in _g_EnumHelper_BmeStructType.get_bme_identifiers():
+            # draw operator
+            cop = layout.operator(
+                cls.bl_idname,
+                text = _g_EnumHelper_BmeStructType.get_bme_showcase_title(ident),
+                icon_value = _g_EnumHelper_BmeStructType.get_bme_showcase_icon(ident),
+                text_ctxt = UTIL_translation.build_prototype_showcase_context(ident)
+            )
+            # and assign its init type value
+            cop.bme_struct_type = _g_EnumHelper_BmeStructType.to_selection(ident)
+
+#endregion
+
+def register() -> None:
+    bpy.utils.register_class(BBP_PG_bme_adder_cfgs)
+    bpy.utils.register_class(BBP_OT_add_bme_struct)
+
+def unregister() -> None:
+    bpy.utils.unregister_class(BBP_OT_add_bme_struct)
+    bpy.utils.unregister_class(BBP_PG_bme_adder_cfgs)

bbp_ng/OP_ADDS_component.py

@@ -0,0 +1,632 @@
+import bpy, mathutils
+import math, typing
+from . import UTIL_functions, UTIL_icons_manager, UTIL_naming_convension
+from . import PROP_ballance_element, PROP_virtools_group, PROP_ballance_map_info
+
+#region Param Help Classes
+
+class ComponentSectorParam():
+    component_sector: bpy.props.IntProperty(
+        name = "Sector",
+        description = "The sector which this component will be grouped in.",
+        min = 1, max = 999,
+        soft_min = 1, soft_max = 8,
+        default = 1,
+        translation_context = 'BBP/OP_ADDS_component.ComponentSectorParam/property'
+    ) # type: ignore
+
+    def general_get_component_sector(self) -> int:
+        return self.component_sector
+    
+    def draw_component_sector_params(self, layout: bpy.types.UILayout) -> None:
+        layout.prop(self, 'component_sector')
+
+class ComponentCountParam():
+    component_count: bpy.props.IntProperty(
+        name = "Count",
+        description = "The count of components which you want to generate",
+        min = 1, max = 64,
+        soft_min = 1, soft_max = 32,
+        default = 1,
+        translation_context = 'BBP/OP_ADDS_component.ComponentCountParam/property'
+    ) # type: ignore
+
+    def general_get_component_count(self) -> int:
+        return self.component_count
+
+    def draw_component_count_params(self, layout: bpy.types.UILayout) -> None:
+        layout.prop(self, 'component_count')
+
+#endregion
+
+#region Help Classes & Functions
+
+def _get_component_info(comp_type: PROP_ballance_element.BallanceElementType, comp_sector: int) -> UTIL_naming_convension.BallanceObjectInfo:
+    match(comp_type):
+        # process for 2 special unique components
+        case PROP_ballance_element.BallanceElementType.PS_FourFlames:
+            return UTIL_naming_convension.BallanceObjectInfo.create_from_others(UTIL_naming_convension.BallanceObjectType.LEVEL_START)
+        case PROP_ballance_element.BallanceElementType.PE_Balloon:
+            return UTIL_naming_convension.BallanceObjectInfo.create_from_others(UTIL_naming_convension.BallanceObjectType.LEVEL_END)
+        # process naming convention required special components
+        case PROP_ballance_element.BallanceElementType.PC_TwoFlames:
+            return UTIL_naming_convension.BallanceObjectInfo.create_from_checkpoint(comp_sector)
+        case PROP_ballance_element.BallanceElementType.PR_Resetpoint:
+            return UTIL_naming_convension.BallanceObjectInfo.create_from_resetpoint(comp_sector)
+        # process for other components
+        case _:
+            return UTIL_naming_convension.BallanceObjectInfo.create_from_component(
+                PROP_ballance_element.get_ballance_element_name(comp_type), 
+                comp_sector
+            )
+    
+def _set_component_by_info(obj: bpy.types.Object, info: UTIL_naming_convension.BallanceObjectInfo) -> None:
+    # set component name and grouping it into virtools group at the same time
+    # set name first
+    if not UTIL_naming_convension.YYCToolchainConvention.set_to_object(obj, info, None):
+        raise UTIL_functions.BBPException('impossible fail to set component name.')
+
+    # set vt group next
+    if not UTIL_naming_convension.VirtoolsGroupConvention.set_to_object(obj, info, None):
+        raise UTIL_functions.BBPException('impossible fail to set component virtools groups.')
+
+def _check_component_existance(comp_type: PROP_ballance_element.BallanceElementType, comp_sector: int) -> str | None:
+    """
+    Check the existance of 4 special components name, PS, PE, PC, PR
+    These 4 components will have special name.
+
+    @return Return name if selected component is one of PS, PE, PC, PR and there already is a name conflict, otherwise None.
+    """
+    # check component type requirements
+    match(comp_type):
+        case PROP_ballance_element.BallanceElementType.PS_FourFlames | PROP_ballance_element.BallanceElementType.PE_Balloon | PROP_ballance_element.BallanceElementType.PC_TwoFlames | PROP_ballance_element.BallanceElementType.PR_Resetpoint:
+            pass    # exit match and start check
+        case _:
+            return None # return, do not check
+    
+    # get info
+    comp_info: UTIL_naming_convension.BallanceObjectInfo = _get_component_info(comp_type, comp_sector)
+    
+    # get expected name
+    expect_name: str | None = UTIL_naming_convension.YYCToolchainConvention.set_to_name(comp_info, None)
+    if expect_name is None:
+        raise UTIL_functions.BBPException('impossible fail to get component name.')
+    
+    # check expected name
+    if expect_name in bpy.data.objects: return expect_name
+    else: return None
+
+class _GeneralComponentCreator():
+    """
+    The assist class for general component creation function.
+    Because we need select all created component, thus we need collect all created object into a list.
+    This is the reason why we create this class.
+    """
+
+    ## The list storing all created component within this creation.
+    __mObjList: list[bpy.types.Object]
+
+    def __init__(self):
+        self.__mObjList = []
+            
+    def create_component(self,
+            comp_type: PROP_ballance_element.BallanceElementType, 
+            comp_sector: int, 
+            comp_count: int, 
+            comp_offset: typing.Callable[[int], mathutils.Matrix]
+        ) -> None:
+        """
+        General component creation function.
+
+        @param comp_type[in] The component type created.
+        @param comp_sector[in] The sector param which passed to other functions. For non-sector component, pass any number.
+        @param comp_count[in] The count of created component. For single component creation, please pass 1.
+        @param comp_offset[in] The function pointer which receive 1 argument indicating the index of object which we want to get its offset.
+            You can pass `lambda _: mathutils.Matrix.Identity(4)` to get zero offset for every items.
+            You can pass `lambda _: mathutils.Matrix( xxx )` to get same offset for every items.
+            You can pass `lambda i: mathutils.Matrix( func(i) )` to get index based offset for each items.
+            The offset is the offset to the origin point, not the previous object.
+        @return The created component instance.
+        """
+        # get element info first
+        ele_info: UTIL_naming_convension.BallanceObjectInfo = _get_component_info(comp_type, comp_sector)
+        
+        # create blc element context
+        with PROP_ballance_element.BallanceElementsHelper(bpy.context.scene) as creator:
+            # object creation counter
+            for i in range(comp_count):
+                # get mesh from element context, and create with empty name first. we assign name later.
+                obj: bpy.types.Object = bpy.data.objects.new('', creator.get_element(comp_type))
+                # assign virtools group, object name by we gotten element info.
+                _set_component_by_info(obj, ele_info)
+                # add into scene and move to cursor
+                UTIL_functions.add_into_scene_and_move_to_cursor(obj)
+                # move with extra offset by calling offset getter
+                obj.matrix_world = obj.matrix_world @ comp_offset(i)
+                # put into created object list
+                self.__mObjList.append(obj)
+
+        # enlarge scene sector field for non-PS (start point) PE (end point) component
+        # read from scene and create var for enlarged sector count
+        map_info: PROP_ballance_map_info.RawBallanceMapInfo = PROP_ballance_map_info.get_raw_ballance_map_info(bpy.context.scene)
+        enlarged_sector: int
+        # check component type to get enlarged value
+        match(ele_info.mBasicType):
+            case UTIL_naming_convension.BallanceObjectType.COMPONENT:
+                enlarged_sector = comp_sector
+            case UTIL_naming_convension.BallanceObjectType.CHECKPOINT:
+                # checkpoint 1 means that there is sector 2, so we plus 1 for it.
+                enlarged_sector = comp_sector + 1
+            case UTIL_naming_convension.BallanceObjectType.RESETPOINT:
+                enlarged_sector = comp_sector
+            case _:
+                # this component is not a sector based component
+                # so we do not change it (use original value)
+                enlarged_sector = map_info.mSectorCount
+        # enlarge it
+        map_info.mSectorCount = max(map_info.mSectorCount, enlarged_sector)
+        PROP_ballance_map_info.set_raw_ballance_map_info(bpy.context.scene, map_info)
+
+    def finish_component(self) -> None:
+        """
+        Finish up component creation.
+        Just deselect all objects and select all created components.
+        """
+        UTIL_functions.select_certain_objects(tuple(self.__mObjList))
+
+#endregion
+
+#region Noemal Component Adder
+
+# element enum prop helper
+
+def _get_component_icon_by_name(elename: str):
+    icon: int | None = UTIL_icons_manager.get_component_icon(elename)
+    if icon is None: return UTIL_icons_manager.get_empty_icon()
+    else: return icon
+_g_EnumHelper_Component: UTIL_functions.EnumPropHelper = UTIL_functions.EnumPropHelper(
+    PROP_ballance_element.BallanceElementType,
+    lambda x: str(x.value),
+    lambda x: PROP_ballance_element.BallanceElementType(int(x)),
+    lambda x: x.name,
+    lambda x: '',
+    lambda x: _get_component_icon_by_name(PROP_ballance_element.get_ballance_element_name(x)),
+)
+
+class BBP_OT_add_component(bpy.types.Operator, ComponentSectorParam):
+    """Add ordinary Component"""
+    bl_idname = "bbp.add_component"
+    bl_label = "Add Component"
+    bl_options = {'UNDO'}
+    bl_translation_context = 'BBP_OT_add_component'
+
+    component_type: bpy.props.EnumProperty(
+        name = "Type",
+        description = "The type of this component.",
+        items = _g_EnumHelper_Component.generate_items(),
+        translation_context = 'BBP_OT_add_component/property'
+    ) # type: ignore
+
+    def invoke(self, context, event):
+        wm = context.window_manager
+        return wm.invoke_props_dialog(self)
+
+    def draw(self, context):
+        layout = self.layout
+        # show type
+        layout.prop(self, "component_type")
+
+        # only show sector for non-PE/PS component
+        eletype: PROP_ballance_element.BallanceElementType = _g_EnumHelper_Component.get_selection(self.component_type)
+        if eletype != PROP_ballance_element.BallanceElementType.PS_FourFlames and eletype != PROP_ballance_element.BallanceElementType.PE_Balloon:
+            self.draw_component_sector_params(layout)
+
+        # check for some special components and show warning
+        elename: str | None = _check_component_existance(_g_EnumHelper_Component.get_selection(self.component_type), self.general_get_component_sector())
+        if elename is not None:
+            tr_text: str = bpy.app.translations.pgettext_iface(
+                'Warning: {0} already exist.', 'BBP_OT_add_component/draw')
+            layout.label(text=tr_text.format(elename), translate=False)
+
+    def execute(self, context):
+        # call general creator
+        creator: _GeneralComponentCreator = _GeneralComponentCreator()
+        creator.create_component(
+            _g_EnumHelper_Component.get_selection(self.component_type),
+            self.general_get_component_sector(),
+            1,  # only create one
+            lambda _: mathutils.Matrix.Identity(4)
+        )
+        creator.finish_component()
+        return {'FINISHED'}
+
+    @staticmethod
+    def draw_blc_menu(layout: bpy.types.UILayout):
+        for item in PROP_ballance_element.BallanceElementType:
+            item_name: str = PROP_ballance_element.get_ballance_element_name(item)
+
+            cop = layout.operator(
+                BBP_OT_add_component.bl_idname,
+                text = item_name, text_ctxt = 'BBP_OT_add_component/property',
+                icon_value = UTIL_icons_manager.get_component_icon(item_name),
+            )
+            cop.component_type = _g_EnumHelper_Component.to_selection(item)
+
+#endregion
+
+#region Nong Comp Adder
+
+class BBP_OT_add_nong_extra_point(bpy.types.Operator, ComponentSectorParam, ComponentCountParam):
+    """Add Nong Extra Point"""
+    bl_idname = "bbp.add_nong_extra_point"
+    bl_label = "Nong Extra Point"
+    bl_options = {'REGISTER', 'UNDO'}
+    bl_translation_context = 'BBP_OT_add_nong_extra_point'
+
+    def draw(self, context):
+        layout = self.layout
+        self.draw_component_sector_params(layout)
+        self.draw_component_count_params(layout)
+
+    def execute(self, context):
+        # create objects and rotate it by a certain degree calculated by its index
+        # calc percent first
+        percent: float = 1.0 / self.general_get_component_count()
+        # create elements
+        creator: _GeneralComponentCreator = _GeneralComponentCreator()
+        creator.create_component(
+            PROP_ballance_element.BallanceElementType.P_Extra_Point,
+            self.general_get_component_sector(),
+            self.general_get_component_count(),
+            lambda i: mathutils.Matrix.Rotation(percent * i * math.pi * 2, 4, 'Z')
+        )
+        creator.finish_component()
+        return {'FINISHED'}
+
+    @staticmethod
+    def draw_blc_menu(layout: bpy.types.UILayout):
+        layout.operator(
+            BBP_OT_add_nong_extra_point.bl_idname,
+            icon_value = UTIL_icons_manager.get_component_icon(
+                PROP_ballance_element.get_ballance_element_name(PROP_ballance_element.BallanceElementType.P_Extra_Point)
+            )
+        )
+
+class BBP_OT_add_nong_ventilator(bpy.types.Operator, ComponentSectorParam, ComponentCountParam):
+    """Add Nong Ventilator"""
+    bl_idname = "bbp.add_nong_ventilator"
+    bl_label = "Nong Ventilator"
+    bl_options = {'REGISTER', 'UNDO'}
+    bl_translation_context = 'BBP_OT_add_nong_ventilator'
+
+    ventilator_count_source: bpy.props.EnumProperty(
+        name = "Ventilator Count Source",
+        items = [
+            ('DEFINED', "Predefined", "Pre-defined ventilator count."),
+            ('CUSTOM', "Custom", "User specified ventilator count."),
+        ],
+        translation_context = 'BBP_OT_add_nong_ventilator/property'
+    ) # type: ignore
+    
+    preset_vetilator_count: bpy.props.EnumProperty(
+        name = "Preset Count",
+        description = "Pick preset ventilator count.",
+        items = [
+            # (token, display name, descriptions, icon, index)
+            ('PAPER', 'Paper', 'The ventilator count (1) can push paper ball up.'),
+            ('WOOD', 'Wood', 'The ventilator count (6) can push wood ball up.'),
+            ('STONE', 'Stone', 'The ventilator count (32) can push stone ball up.'),
+        ],
+        translation_context = 'BBP_OT_add_nong_ventilator/property'
+    ) # type: ignore
+
+    def draw(self, context):
+        layout = self.layout
+        # draw sector settings
+        self.draw_component_sector_params(layout)
+
+        # draw count settings by different source
+        layout.separator()
+        layout.label(text='Count Source', text_ctxt='BBP_OT_add_nong_ventilator/draw')
+        layout.prop(self, 'ventilator_count_source', expand = True)
+        if (self.ventilator_count_source == 'CUSTOM'):
+            self.draw_component_count_params(layout)
+        else:
+            layout.prop(self, 'preset_vetilator_count')
+        
+    def execute(self, context):
+        # get ventilator count
+        count: int = 0
+        if (self.ventilator_count_source == 'CUSTOM'):
+            count = self.general_get_component_count()
+        else:
+            match(self.preset_vetilator_count):
+                case 'PAPER': count = 1
+                case 'WOOD': count = 6
+                case 'STONE': count = 32
+                case _: raise UTIL_functions.BBPException('invalid enumprop data')
+                
+        # create elements without any move
+        creator: _GeneralComponentCreator = _GeneralComponentCreator()
+        creator.create_component(
+            PROP_ballance_element.BallanceElementType.P_Modul_18,
+            self.general_get_component_sector(),
+            count,
+            lambda _: mathutils.Matrix.Identity(4)
+        )
+        creator.finish_component()
+        return {'FINISHED'}
+
+    @staticmethod
+    def draw_blc_menu(layout: bpy.types.UILayout):
+        layout.operator(
+            BBP_OT_add_nong_ventilator.bl_idname,
+            icon_value = UTIL_icons_manager.get_component_icon(
+                PROP_ballance_element.get_ballance_element_name(PROP_ballance_element.BallanceElementType.P_Modul_18)
+            )
+        )
+
+#endregion
+
+#region Series Comp Adder
+
+class BBP_OT_add_tilting_block_series(bpy.types.Operator, ComponentSectorParam, ComponentCountParam):
+    """Add Tilting Block Series"""
+    bl_idname = "bbp.add_tilting_block_series"
+    bl_label = "Tilting Block Series"
+    bl_options = {'REGISTER', 'UNDO'}
+    bl_translation_context = 'BBP_OT_add_tilting_block_series'
+
+    component_span: bpy.props.FloatProperty(
+        name = "Span",
+        description = "The distance between each titling blocks",
+        min = 0.0, max = 100.0,
+        soft_min = 0.0, soft_max = 12.0,
+        default = 6.0022,
+        translation_context = 'BBP_OT_add_tilting_block_series/property'
+    ) # type: ignore
+
+    def draw(self, context):
+        layout = self.layout
+        self.draw_component_sector_params(layout)
+        self.draw_component_count_params(layout)
+        layout.prop(self, 'component_span')
+
+    def execute(self, context):
+        # create objects and move it by delta
+        # get span first
+        span: float = self.component_span
+        # create elements
+        creator: _GeneralComponentCreator = _GeneralComponentCreator()
+        creator.create_component(
+            PROP_ballance_element.BallanceElementType.P_Modul_41,
+            self.general_get_component_sector(),
+            self.general_get_component_count(),
+            lambda i: mathutils.Matrix.Translation(mathutils.Vector((span * i, 0.0, 0.0)))  # move with extra delta in x axis
+        )
+        creator.finish_component()
+        return {'FINISHED'}
+
+    @staticmethod
+    def draw_blc_menu(layout: bpy.types.UILayout):
+        layout.operator(
+            BBP_OT_add_tilting_block_series.bl_idname,
+            icon_value = UTIL_icons_manager.get_component_icon(
+                PROP_ballance_element.get_ballance_element_name(PROP_ballance_element.BallanceElementType.P_Modul_41)
+            )
+        )
+
+class BBP_OT_add_swing_series(bpy.types.Operator, ComponentSectorParam, ComponentCountParam):
+    """Add Swing Series"""
+    bl_idname = "bbp.add_swing_series"
+    bl_label = "Swing Series"
+    bl_options = {'REGISTER', 'UNDO'}
+    bl_translation_context = 'BBP_OT_add_swing_series'
+
+    component_span: bpy.props.FloatProperty(
+        name = "Span",
+        description = "The distance between each swing",
+        min = 0.0, max = 100.0,
+        soft_min = 0.0, soft_max = 30.0,
+        default = 15.0,
+        translation_context = 'BBP_OT_add_swing_series/property'
+    ) # type: ignore
+
+    staggered_swing: bpy.props.BoolProperty(
+        name = 'Staggered', 
+        description = 'Whether place Swing staggered. Staggered Swing accept any ball however Non-Staggered Swing only accept Wood and Paper ball.',
+        default = True,
+        translation_context = 'BBP_OT_add_swing_series/property'
+    ) # type: ignore
+
+    def draw(self, context):
+        layout = self.layout
+        self.draw_component_sector_params(layout)
+        self.draw_component_count_params(layout)
+        layout.prop(self, 'component_span')
+        layout.prop(self, 'staggered_swing')
+
+    def execute(self, context):
+        # create objects and move it by delta
+        # get span first
+        span: float = self.component_span
+        staggered: bool = self.staggered_swing
+        # create elements
+        creator: _GeneralComponentCreator = _GeneralComponentCreator()
+        creator.create_component(
+            PROP_ballance_element.BallanceElementType.P_Modul_08,
+            self.general_get_component_sector(),
+            self.general_get_component_count(),
+            lambda i: mathutils.Matrix.LocRotScale(
+                # move with extra delta in x axis
+                mathutils.Vector((span * i, 0.0, 0.0)),
+                # and rotate 90 degree for even one if staggered placement.
+                mathutils.Euler((0, 0, math.radians(180) if (staggered and (i % 2 == 0)) else 0)),
+                None
+            )
+        )
+        creator.finish_component()
+        return {'FINISHED'}
+
+    @staticmethod
+    def draw_blc_menu(layout: bpy.types.UILayout):
+        layout.operator(
+            BBP_OT_add_swing_series.bl_idname,
+            icon_value = UTIL_icons_manager.get_component_icon(
+                PROP_ballance_element.get_ballance_element_name(PROP_ballance_element.BallanceElementType.P_Modul_08)
+            )
+        )
+
+class BBP_OT_add_ventilator_series(bpy.types.Operator, ComponentSectorParam, ComponentCountParam):
+    """Add Ventilator Series"""
+    bl_idname = "bbp.add_ventilator_series"
+    bl_label = "Ventilator Series"
+    bl_options = {'REGISTER', 'UNDO'}
+    bl_translation_context = 'BBP_OT_add_ventilator_series'
+
+    component_translation: bpy.props.FloatVectorProperty(
+        name = "Delta Vector",
+        description = "The translation between each ventilators. You can use this property to implement vertical or horizontal ventilator series. Set all factors to zero can get Nong ventilator.",
+        size = 3, subtype = 'TRANSLATION',
+        min = 0.0, max = 100.0,
+        soft_min = 0.0, soft_max = 50.0,
+        default = (0.0, 0.0, 15.0),
+        translation_context = 'BBP_OT_add_ventilator_series/property'
+    ) # type: ignore
+
+    def draw(self, context):
+        layout = self.layout
+        self.draw_component_sector_params(layout)
+        self.draw_component_count_params(layout)
+        layout.prop(self, 'component_translation')
+
+    def execute(self, context):
+        # create objects and move it by delta
+        # get translation first
+        translation: mathutils.Vector = mathutils.Vector(self.component_translation)
+        # create elements
+        creator: _GeneralComponentCreator = _GeneralComponentCreator()
+        creator.create_component(
+            PROP_ballance_element.BallanceElementType.P_Modul_18,
+            self.general_get_component_sector(),
+            self.general_get_component_count(),
+            lambda i: mathutils.Matrix.Translation(i * translation)  # move with extra translation
+        )
+        creator.finish_component()
+        return {'FINISHED'}
+
+    @staticmethod
+    def draw_blc_menu(layout: bpy.types.UILayout):
+        layout.operator(
+            BBP_OT_add_ventilator_series.bl_idname,
+            icon_value = UTIL_icons_manager.get_component_icon(
+                PROP_ballance_element.get_ballance_element_name(PROP_ballance_element.BallanceElementType.P_Modul_18)
+            )
+        )
+
+#endregion
+
+#region Comp Pair Adder
+
+class BBP_OT_add_sector_component_pair(bpy.types.Operator, ComponentSectorParam):
+    """Add Sector Pair, both check point and reset point."""
+    bl_idname = "bbp.add_sector_component_pair"
+    bl_label = "Sector Pair"
+    bl_options = {'UNDO'}
+    bl_translation_context = 'BBP_OT_add_sector_component_pair'
+
+    def __get_checkpoint(self) -> tuple[PROP_ballance_element.BallanceElementType, int]:
+        if self.general_get_component_sector() == 1:
+            return (PROP_ballance_element.BallanceElementType.PS_FourFlames, 1)
+        else:
+            # the sector of two flames should be `sector - 1` because first one was occupied by FourFlams
+            return (PROP_ballance_element.BallanceElementType.PC_TwoFlames, self.general_get_component_sector() - 1)
+
+    def __get_resetpoint(self) -> tuple[PROP_ballance_element.BallanceElementType, int]:
+        # resetpoint's sector is just sector it self.
+        return (PROP_ballance_element.BallanceElementType.PR_Resetpoint, self.general_get_component_sector())
+
+    def invoke(self, context, event):
+        wm = context.window_manager
+        return wm.invoke_props_dialog(self)
+
+    def draw(self, context):
+        layout = self.layout
+        self.draw_component_sector_params(layout)
+
+        # fetch warning string
+        tr_text: str = bpy.app.translations.pgettext_iface(
+            'Warning: {0} already exist.', 'BBP_OT_add_sector_component_pair/draw')
+
+        # check checkpoint and resetpoint name conflict and show warnings
+        (checkp_ty, checkp_sector) = self.__get_checkpoint()
+        elename: str | None = _check_component_existance(checkp_ty, checkp_sector)
+        if elename is not None:
+            layout.label(text=tr_text.format(elename), translate=False)
+
+        (resetp_ty, resetp_sector) = self.__get_resetpoint()
+        elename = _check_component_existance(resetp_ty, resetp_sector)
+        if elename is not None:
+            layout.label(text=tr_text.format(elename), translate=False)
+
+    def execute(self, context):
+        # create checkpoint and resetpoint individually in element context
+        # get type and sector data first
+        (checkp_ty, checkp_sector) = self.__get_checkpoint()
+        (resetp_ty, resetp_sector) = self.__get_resetpoint()
+        # calc resetpoint offset
+        # resetpoint need a extra offset between checkpoint
+        # but it is different in FourFlams and TwoFlams
+        resetp_offset: float
+        if checkp_ty == PROP_ballance_element.BallanceElementType.PS_FourFlames:
+            resetp_offset = 3.25
+        else:
+            resetp_offset = 2.0
+
+        # add elements
+        # create checkpoint
+        creator: _GeneralComponentCreator = _GeneralComponentCreator()
+        creator.create_component(
+            checkp_ty,
+            checkp_sector,
+            1,  # only create one
+            lambda _: mathutils.Matrix.Identity(4)
+        )
+        # create resetpoint
+        creator.create_component(
+            resetp_ty,
+            resetp_sector,
+            1,  # only create one
+            lambda _: mathutils.Matrix.Translation(mathutils.Vector((0.0, 0.0, resetp_offset))) # apply resetpoint offset
+        )
+        creator.finish_component()
+        return {'FINISHED'}
+
+    @staticmethod
+    def draw_blc_menu(layout: bpy.types.UILayout):
+        layout.operator(
+            BBP_OT_add_sector_component_pair.bl_idname,
+            icon_value = UTIL_icons_manager.get_component_icon(
+                PROP_ballance_element.get_ballance_element_name(PROP_ballance_element.BallanceElementType.PR_Resetpoint)
+            )
+        )
+
+#endregion
+
+def register() -> None:
+    bpy.utils.register_class(BBP_OT_add_component)
+    bpy.utils.register_class(BBP_OT_add_nong_extra_point)
+    bpy.utils.register_class(BBP_OT_add_nong_ventilator)
+    bpy.utils.register_class(BBP_OT_add_tilting_block_series)
+    bpy.utils.register_class(BBP_OT_add_swing_series)
+    bpy.utils.register_class(BBP_OT_add_ventilator_series)
+    bpy.utils.register_class(BBP_OT_add_sector_component_pair)
+
+def unregister() -> None:
+    bpy.utils.unregister_class(BBP_OT_add_sector_component_pair)
+    bpy.utils.unregister_class(BBP_OT_add_ventilator_series)
+    bpy.utils.unregister_class(BBP_OT_add_swing_series)
+    bpy.utils.unregister_class(BBP_OT_add_tilting_block_series)
+    bpy.utils.unregister_class(BBP_OT_add_nong_ventilator)
+    bpy.utils.unregister_class(BBP_OT_add_nong_extra_point)
+    bpy.utils.unregister_class(BBP_OT_add_component)

bbp_ng/OP_ADDS_rail.py

@@ -0,0 +1,528 @@
+import bpy, mathutils, math
+import typing
+from . import UTIL_rail_creator
+
+## Const Value Hint:
+#  Default Rail Radius: 0.35 (in measure)
+#  Default Rail Span: 3.75 (in convention)
+#  Default Monorail Sink Depth in Rail & Monorail Transition: 0.6259 (calculated by ImbalancedDream)
+#      Equation: Sink = sqrt( ((RailRadius + BallRadius) ^ 2) - ((RailSpan / 2) ^ 2)  ) - BallRadius - RailRadius
+#      BallRadius is the radius of player ball. It always is 2.
+#      Ref: https://tieba.baidu.com/p/6557180791
+#  
+#  For Normal Side Rail (paper ball + wood ball can pass it):
+#  Rail Span: 3.864
+#  Angle (between rail panel and XY panel): 79.563 degree
+#  For Special Side Rail (stone ball can pass it):
+#  Rail Span: 3.864
+#  Angle (between rail panel and XY panel): 57 degree
+#  These infos are gotten from BallanceBug.
+#  
+#  For Side Spiral Rail, the distance between each layer is 3.6
+#  Measured in Level 9 and Level 13.
+#  For Spiral Rail, the distance between each layer is 5
+#  Measured in Level 10.
+
+c_DefaultRailRadius: float = 0.35
+c_DefaultRailSpan: float = 3.75
+c_SideRailSpan: float = 3.864
+c_NormalSideRailAngle: float = 79.563
+c_StoneSideRailAngle: float = 57
+c_SpiralRailScrew: float = 5
+c_SideSpiralRailScrew: float = 3.6
+
+#region Operator Helpers
+
+class SharedExtraTransform():
+    """
+    This class is served for all rail creation which allow user 
+    provide extra transform after moving created rail to cursor.
+    For "what you look is what you gotten" experience, this extra transform is essential.
+    """
+
+    extra_translation: bpy.props.FloatVectorProperty(
+        name = "Extra Translation",
+        description = "The extra translation applied to object after moving to cursor.",
+        size = 3,
+        subtype = 'TRANSLATION',
+        step = 50, # same step as the float entry of BBP_PG_bme_adder_cfgs
+        default = (0.0, 0.0, 0.0),
+        translation_context = 'BBP/OP_ADDS_rail.SharedExtraTransform/property'
+    ) # type: ignore
+    extra_rotation: bpy.props.FloatVectorProperty(
+        name = "Extra Rotation",
+        description = "The extra rotation applied to object after moving to cursor.",
+        size = 3,
+        subtype = 'EULER',
+        step = 100, # We choosen 100, mean 1. Sync with property window.
+        default = (0.0, 0.0, 0.0),
+        translation_context = 'BBP/OP_ADDS_rail.SharedExtraTransform/property'
+    ) # type: ignore
+
+    def draw_extra_transform_input(self, layout: bpy.types.UILayout) -> None:
+        # show extra transform props
+        # forcely order that each one are placed horizontally
+        layout.label(text="Extra Transform", text_ctxt='BBP/OP_ADDS_rail.SharedExtraTransform/draw')
+        # translation
+        layout.label(text='Translation', text_ctxt='BBP/OP_ADDS_rail.SharedExtraTransform/draw')
+        row = layout.row()
+        row.prop(self, 'extra_translation', text='')
+        # rotation
+        layout.label(text='Rotation', text_ctxt='BBP/OP_ADDS_rail.SharedExtraTransform/draw')
+        row = layout.row()
+        row.prop(self, 'extra_rotation', text='')
+
+    def general_get_extra_transform(self) -> mathutils.Matrix:
+        return mathutils.Matrix.LocRotScale(
+            mathutils.Vector(self.extra_translation),
+            mathutils.Euler(self.extra_rotation, 'XYZ'),
+            mathutils.Vector((1.0, 1.0, 1.0)) # no scale
+        )
+
+class SharedRailSectionInputProperty():
+    """
+    This class is served for user to pick the transition type of rail.
+    And order rail radius and span accoridng to user picked rail type.
+    """
+    
+    rail_type: bpy.props.EnumProperty(
+        name = "Type",
+        description = "Rail type",
+        items = [
+            ('MONORAIL', "Monorail", ""),
+            ('RAIL', "Rail", ""),
+        ],
+        default = 'RAIL',
+        translation_context = 'BBP/OP_ADDS_rail.SharedRailSectionInputProperty/property'
+    ) # type: ignore
+
+    def draw_rail_section_input(self, layout: bpy.types.UILayout) -> None:
+        row = layout.row()
+        row.prop(self, 'rail_type', expand = True)
+
+    def general_get_is_monorail(self) -> bool:
+        return self.rail_type == 'MONORAIL'
+
+class SharedRailCapInputProperty():
+    """
+    This class provide properties for cap switch.
+    Support head cap and tail cap. Both straight and screw rail can use this.
+    """
+
+    rail_start_cap: bpy.props.BoolProperty(
+        name = 'Start Cap',
+        description = 'Whether this rail should have cap at start terminal.',
+        default = False,
+        translation_context = 'BBP/OP_ADDS_rail.SharedRailCapInputProperty/property'
+    ) # type: ignore
+
+    rail_end_cap: bpy.props.BoolProperty(
+        name = 'End Cap',
+        description = 'Whether this rail should have cap at end terminal.',
+        default = False,
+        translation_context = 'BBP/OP_ADDS_rail.SharedRailCapInputProperty/property'
+    ) # type: ignore
+
+    def draw_rail_cap_input(self, layout: bpy.types.UILayout) -> None:
+        layout.label(text="Cap Options", text_ctxt='BBP/OP_ADDS_rail.SharedRailCapInputProperty/draw')
+        row = layout.row()
+        row.prop(self, "rail_start_cap", toggle = 1)
+        row.prop(self, "rail_end_cap", toggle = 1)
+
+    def general_get_rail_start_cap(self) -> bool:
+        return self.rail_start_cap
+    def general_get_rail_end_cap(self) -> bool:
+        return self.rail_end_cap
+
+class SharedStraightRailInputProperty():
+    """
+    The properties for straight rail.
+    """
+
+    rail_length: bpy.props.FloatProperty(
+        name = "Length",
+        description = "The length of this rail.",
+        default = 5.0,
+        min = 0,
+        step = 50, # same unit as BME Struct
+        unit = 'LENGTH',
+        translation_context = 'BBP/OP_ADDS_rail.SharedStraightRailInputProperty/property'
+    ) # type: ignore
+
+    def draw_straight_rail_input(self, layout: bpy.types.UILayout) -> None:
+        layout.prop(self, "rail_length")
+
+    def general_get_rail_length(self) -> float:
+        return self.rail_length
+
+class SharedScrewRailInputProperty():
+    """
+    The properties for straight rail.
+    """
+
+    rail_screw_steps: bpy.props.IntProperty(
+        name = "Steps",
+        description = "The segment count per iteration. More segment, more smooth but lower performance.",
+        default = 28,
+        min = 1,
+        translation_context = 'BBP/OP_ADDS_rail.SharedScrewRailInputProperty/property'
+    ) # type: ignore
+
+    rail_screw_radius: bpy.props.FloatProperty(
+        name = "Radius",
+        description = "The screw radius.",
+        default = 5,
+        min = 0,
+        unit = 'LENGTH',
+        translation_context = 'BBP/OP_ADDS_rail.SharedScrewRailInputProperty/property'
+    ) # type: ignore
+
+    rail_screw_flip_x: bpy.props.BoolProperty(
+        name = 'Flip X',
+        description = 'Whether flip this rail with X axis',
+        default = False,
+        translation_context = 'BBP/OP_ADDS_rail.SharedScrewRailInputProperty/property'
+    ) # type: ignore
+
+    rail_screw_flip_y: bpy.props.BoolProperty(
+        name = 'Flip Y',
+        description = 'Whether flip this rail with Y axis',
+        default = False,
+        translation_context = 'BBP/OP_ADDS_rail.SharedScrewRailInputProperty/property'
+    ) # type: ignore
+
+    rail_screw_flip_z: bpy.props.BoolProperty(
+        name = 'Flip Z',
+        description = 'Whether flip this rail with Z axis',
+        default = False,
+        translation_context = 'BBP/OP_ADDS_rail.SharedScrewRailInputProperty/property'
+    ) # type: ignore
+
+    def draw_screw_rail_input(self, layout: bpy.types.UILayout) -> None:
+        layout.prop(self, "rail_screw_radius")
+        layout.prop(self, "rail_screw_steps")
+
+    def general_get_rail_screw_radius(self) -> float:
+        return self.rail_screw_radius
+    def general_get_rail_screw_steps(self) -> int:
+        return self.rail_screw_steps
+    
+    def draw_screw_rail_flip_input(self, layout: bpy.types.UILayout) -> None:
+        # flip options should placed horizontally
+        layout.label(text="Flip Options", text_ctxt='BBP/OP_ADDS_rail.SharedScrewRailInputProperty/draw')
+        row = layout.row()
+        row.prop(self, "rail_screw_flip_x", toggle = 1)
+        row.prop(self, "rail_screw_flip_y", toggle = 1)
+        row.prop(self, "rail_screw_flip_z", toggle = 1)
+
+    def general_get_rail_screw_flip_x(self) -> bool:
+        return self.rail_screw_flip_x
+    def general_get_rail_screw_flip_y(self) -> bool:
+        return self.rail_screw_flip_y
+    def general_get_rail_screw_flip_z(self) -> bool:
+        return self.rail_screw_flip_z
+    
+#endregion
+
+#region Operators
+
+class BBP_OT_add_rail_section(SharedRailSectionInputProperty, bpy.types.Operator):
+    """Add Rail Section"""
+    bl_idname = "bbp.add_rail_section"
+    bl_label = "Rail Section"
+    bl_options = {'REGISTER', 'UNDO'}
+    bl_translation_context = 'BBP_OT_add_rail_section'
+
+    def execute(self, context):
+        UTIL_rail_creator.rail_creator_wrapper(
+            lambda bm: UTIL_rail_creator.create_rail_section(
+                bm, self.general_get_is_monorail(), 
+                c_DefaultRailRadius, c_DefaultRailSpan
+            ),
+            mathutils.Matrix.Identity(4)
+        )
+        return {'FINISHED'}
+
+    def draw(self, context):
+        layout = self.layout
+        self.draw_rail_section_input(layout)
+
+class BBP_OT_add_transition_section(bpy.types.Operator):
+    """Add Transition Section"""
+    bl_idname = "bbp.add_transition_section"
+    bl_label = "Transition Section"
+    bl_options = {'REGISTER', 'UNDO'}
+    bl_translation_context = 'BBP_OT_add_transition_section'
+
+    def execute(self, context):
+        UTIL_rail_creator.rail_creator_wrapper(
+            lambda bm: UTIL_rail_creator.create_transition_section(bm, c_DefaultRailRadius, c_DefaultRailSpan),
+            mathutils.Matrix.Identity(4)
+        )
+        return {'FINISHED'}
+
+    def draw(self, context):
+        layout = self.layout
+        layout.label(text='No Options Available', text_ctxt='BBP_OT_add_transition_section/draw')
+
+class BBP_OT_add_straight_rail(SharedExtraTransform, SharedRailSectionInputProperty, SharedRailCapInputProperty, SharedStraightRailInputProperty, bpy.types.Operator):
+    """Add Straight Rail"""
+    bl_idname = "bbp.add_straight_rail"
+    bl_label = "Straight Rail"
+    bl_options = {'REGISTER', 'UNDO'}
+    bl_translation_context = 'BBP_OT_add_straight_rail'
+
+    def execute(self, context):
+        UTIL_rail_creator.rail_creator_wrapper(
+            lambda bm: UTIL_rail_creator.create_straight_rail(
+                bm,
+                self.general_get_is_monorail(), c_DefaultRailRadius, c_DefaultRailSpan,
+                self.general_get_rail_length(), 0,
+                self.general_get_rail_start_cap(), self.general_get_rail_end_cap()
+            ),
+            self.general_get_extra_transform()
+        )
+        return {'FINISHED'}
+
+    def draw(self, context):
+        layout = self.layout
+        layout.label(text='Straight Rail', text_ctxt='BBP_OT_add_straight_rail/draw')
+        self.draw_rail_section_input(layout)
+        self.draw_straight_rail_input(layout)
+        layout.separator()
+        self.draw_rail_cap_input(layout)
+        layout.separator()
+        self.draw_extra_transform_input(layout)
+
+class BBP_OT_add_transition_rail(SharedExtraTransform, SharedRailCapInputProperty, SharedStraightRailInputProperty, bpy.types.Operator):
+    """Add Transition Rail"""
+    bl_idname = "bbp.add_transition_rail"
+    bl_label = "Transition Rail"
+    bl_options = {'REGISTER', 'UNDO'}
+    bl_translation_context = 'BBP_OT_add_transition_rail'
+
+    def execute(self, context):
+        UTIL_rail_creator.rail_creator_wrapper(
+            lambda bm: UTIL_rail_creator.create_transition_rail(
+                bm,
+                c_DefaultRailRadius, c_DefaultRailSpan,
+                self.general_get_rail_length(),
+                self.general_get_rail_start_cap(), self.general_get_rail_end_cap()
+            ),
+            self.general_get_extra_transform()
+        )
+        return {'FINISHED'}
+
+    def draw(self, context):
+        layout = self.layout
+        layout.label(text='Transition Rail', text_ctxt='BBP_OT_add_transition_rail/draw')
+        self.draw_straight_rail_input(layout)
+        layout.separator()
+        self.draw_rail_cap_input(layout)
+        layout.separator()
+        self.draw_extra_transform_input(layout)
+
+class BBP_OT_add_side_rail(SharedExtraTransform, SharedRailCapInputProperty, SharedStraightRailInputProperty, bpy.types.Operator):
+    """Add Side Rail"""
+    bl_idname = "bbp.add_side_rail"
+    bl_label = "Side Rail"
+    bl_options = {'REGISTER', 'UNDO'}
+    bl_translation_context = 'BBP_OT_add_side_rail'
+
+    side_rail_type: bpy.props.EnumProperty(
+        name = "Side Type",
+        description = "Side rail type",
+        items = [
+            ('NORMAL', "Normal", "The normal side rail."),
+            ('STONE', "Stone Specific", "The side rail which also allow stone ball passed."),
+        ],
+        default = 'NORMAL',
+        translation_context = 'BBP_OT_add_side_rail/property'
+    ) # type: ignore
+
+    def execute(self, context):
+        UTIL_rail_creator.rail_creator_wrapper(
+            lambda bm: UTIL_rail_creator.create_straight_rail(
+                bm,
+                False, c_DefaultRailRadius, c_DefaultRailSpan,
+                self.general_get_rail_length(), 
+                c_NormalSideRailAngle if self.side_rail_type == 'NORMAL' else c_StoneSideRailAngle,
+                self.general_get_rail_start_cap(), self.general_get_rail_end_cap()
+            ),
+            self.general_get_extra_transform()
+        )
+        return {'FINISHED'}
+
+    def draw(self, context):
+        layout = self.layout
+        layout.label(text='Side Rail', text_ctxt='BBP_OT_add_side_rail/draw')
+        layout.prop(self, 'side_rail_type')
+        self.draw_straight_rail_input(layout)
+        layout.separator()
+        self.draw_rail_cap_input(layout)
+        layout.separator()
+        self.draw_extra_transform_input(layout)
+
+class BBP_OT_add_arc_rail(SharedExtraTransform, SharedRailSectionInputProperty, SharedRailCapInputProperty, SharedScrewRailInputProperty, bpy.types.Operator):
+    """Add Arc Rail"""
+    bl_idname = "bbp.add_arc_rail"
+    bl_label = "Arc Rail"
+    bl_options = {'REGISTER', 'UNDO'}
+    bl_translation_context = 'BBP_OT_add_arc_rail'
+
+    rail_screw_angle: bpy.props.FloatProperty(
+        name = "Angle",
+        description = "The angle of this arc rail rotated.",
+        default = math.radians(90),
+        min = 0, max = math.radians(360),
+        subtype = 'ANGLE',
+        translation_context = 'BBP_OT_add_arc_rail/property'
+    ) # type: ignore
+
+    def execute(self, context):
+        UTIL_rail_creator.rail_creator_wrapper(
+            lambda bm: UTIL_rail_creator.create_screw_rail(
+                bm,
+                self.general_get_is_monorail(), c_DefaultRailRadius, c_DefaultRailSpan,
+                self.general_get_rail_start_cap(), self.general_get_rail_end_cap(),
+                math.degrees(self.rail_screw_angle), 0, 1,  # blender passed value is in radians
+                self.general_get_rail_screw_steps(), self.general_get_rail_screw_radius(),
+                self.general_get_rail_screw_flip_x(), self.general_get_rail_screw_flip_y(), self.general_get_rail_screw_flip_z()
+            ),
+            self.general_get_extra_transform()
+        )
+        return {'FINISHED'}
+
+    def draw(self, context):
+        layout = self.layout
+        layout.label(text='Arc Rail', text_ctxt='BBP_OT_add_arc_rail/draw')
+        self.draw_rail_section_input(layout)
+        self.draw_screw_rail_input(layout)
+        layout.prop(self, "rail_screw_angle")
+        layout.separator()
+        self.draw_screw_rail_flip_input(layout)
+        layout.separator()
+        self.draw_rail_cap_input(layout)
+        layout.separator()
+        self.draw_extra_transform_input(layout)
+
+class BBP_OT_add_spiral_rail(SharedExtraTransform, SharedRailCapInputProperty, SharedScrewRailInputProperty, bpy.types.Operator):
+    """Add Spiral Rail"""
+    bl_idname = "bbp.add_spiral_rail"
+    bl_label = "Spiral Rail"
+    bl_options = {'REGISTER', 'UNDO'}
+    bl_translation_context = 'BBP_OT_add_spiral_rail'
+
+    rail_screw_screw: bpy.props.FloatProperty(
+        name = "Screw",
+        description = "The increased height in each iteration.",
+        default = c_SpiralRailScrew,
+        min = 0.0,
+        unit = 'LENGTH',
+        translation_context = 'BBP_OT_add_spiral_rail/property'
+    ) # type: ignore
+
+    rail_screw_iterations: bpy.props.IntProperty(
+        name = "Iterations",
+        description = "Indicate how many layers of this spiral rail should be generated.",
+        default = 1,
+        min = 1,
+        translation_context = 'BBP_OT_add_spiral_rail/property'
+    ) # type: ignore
+
+    def execute(self, context):
+        UTIL_rail_creator.rail_creator_wrapper(
+            lambda bm: UTIL_rail_creator.create_screw_rail(
+                bm,
+                False, c_DefaultRailRadius, c_DefaultRailSpan,
+                self.general_get_rail_start_cap(), self.general_get_rail_end_cap(),
+                360, self.rail_screw_screw, self.rail_screw_iterations,
+                self.general_get_rail_screw_steps(), self.general_get_rail_screw_radius(),
+                self.general_get_rail_screw_flip_x(), self.general_get_rail_screw_flip_y(), self.general_get_rail_screw_flip_z()
+            ),
+            self.general_get_extra_transform()
+        )
+        return {'FINISHED'}
+
+    def draw(self, context):
+        layout = self.layout
+        layout.label(text='Spiral Rail', text_ctxt='BBP_OT_add_spiral_rail/draw')
+        self.draw_screw_rail_input(layout)
+        layout.prop(self, "rail_screw_screw")
+        layout.prop(self, "rail_screw_iterations")
+        layout.separator()
+        self.draw_screw_rail_flip_input(layout)
+        layout.separator()
+        self.draw_rail_cap_input(layout)
+        layout.separator()
+        self.draw_extra_transform_input(layout)
+
+class BBP_OT_add_side_spiral_rail(SharedExtraTransform, SharedRailSectionInputProperty, SharedRailCapInputProperty, SharedScrewRailInputProperty, bpy.types.Operator):
+    """Add Side Spiral Rail"""
+    bl_idname = "bbp.add_side_spiral_rail"
+    bl_label = "Side Spiral Rail"
+    bl_options = {'REGISTER', 'UNDO'}
+    bl_translation_context = 'BBP_OT_add_side_spiral_rail'
+
+    rail_screw_iterations: bpy.props.IntProperty(
+        name = "Iterations",
+        description = "Indicate how many layers of this spiral rail should be generated.",
+        default = 2,
+        # at least 2 ietrations can create 1 useful side spiral rail.
+        # becuase side spiral rail is edge shared.
+        min = 2,
+        translation_context = 'BBP_OT_add_side_spiral_rail/property'
+    ) # type: ignore
+
+    def execute(self, context):
+        UTIL_rail_creator.rail_creator_wrapper(
+            lambda bm: UTIL_rail_creator.create_screw_rail(
+                bm,
+                True, c_DefaultRailRadius, c_DefaultRailSpan,
+                self.general_get_rail_start_cap(), self.general_get_rail_end_cap(),
+                360, c_SideSpiralRailScrew, self.rail_screw_iterations,
+                self.general_get_rail_screw_steps(), self.general_get_rail_screw_radius(),
+                self.general_get_rail_screw_flip_x(), self.general_get_rail_screw_flip_y(), self.general_get_rail_screw_flip_z()
+            ),
+            self.general_get_extra_transform()
+        )
+        return {'FINISHED'}
+
+    def draw(self, context):
+        layout = self.layout
+        layout.label(text='Spiral Rail', text_ctxt='BBP_OT_add_side_spiral_rail/draw')
+        self.draw_screw_rail_input(layout)
+        layout.prop(self, "rail_screw_iterations")
+        layout.separator()
+        self.draw_screw_rail_flip_input(layout)
+        layout.separator()
+        self.draw_rail_cap_input(layout)
+        layout.separator()
+        self.draw_extra_transform_input(layout)
+
+#endregion
+
+def register() -> None:
+    bpy.utils.register_class(BBP_OT_add_rail_section)
+    bpy.utils.register_class(BBP_OT_add_transition_section)
+
+    bpy.utils.register_class(BBP_OT_add_straight_rail)
+    bpy.utils.register_class(BBP_OT_add_transition_rail)
+    bpy.utils.register_class(BBP_OT_add_side_rail)
+
+    bpy.utils.register_class(BBP_OT_add_arc_rail)
+    bpy.utils.register_class(BBP_OT_add_spiral_rail)
+    bpy.utils.register_class(BBP_OT_add_side_spiral_rail)
+
+
+def unregister() -> None:
+    bpy.utils.unregister_class(BBP_OT_add_side_spiral_rail)
+    bpy.utils.unregister_class(BBP_OT_add_spiral_rail)
+    bpy.utils.unregister_class(BBP_OT_add_arc_rail)
+
+    bpy.utils.unregister_class(BBP_OT_add_side_rail)
+    bpy.utils.unregister_class(BBP_OT_add_transition_rail)
+    bpy.utils.unregister_class(BBP_OT_add_straight_rail)
+
+    bpy.utils.unregister_class(BBP_OT_add_transition_section)
+    bpy.utils.unregister_class(BBP_OT_add_rail_section)

bbp_ng/OP_EXPORT_bmfile.py

@@ -0,0 +1,28 @@
+import bpy
+from . import PROP_preferences, UTIL_functions, UTIL_file_browser, UTIL_blender_mesh, UTIL_ioport_shared
+
+class BBP_OT_export_bmfile(bpy.types.Operator, UTIL_file_browser.ExportBmxFile, UTIL_ioport_shared.ExportParams):
+    """Save a Ballance Map File (BM File Spec 1.4)"""
+    bl_idname = "bbp.export_bmfile"
+    bl_label = "Export BM (Ballance Map) File"
+    bl_options = {'PRESET'}
+    bl_translation_context = 'BBP_OT_export_bmfile'
+
+    @classmethod
+    def poll(cls, context):
+        return PROP_preferences.get_raw_preferences().has_valid_blc_tex_folder()
+    
+    def execute(self, context):
+        self.report({'ERROR'}, 'This feature is not supported yet.')
+        # self.report({'INFO'}, "BM File Exporting Finished.")
+        return {'FINISHED'}
+    
+    def draw(self, context):
+        layout = self.layout
+        self.draw_export_params(context, layout.box())
+
+def register() -> None:
+    bpy.utils.register_class(BBP_OT_export_bmfile)
+
+def unregister() -> None:
+    bpy.utils.unregister_class(BBP_OT_export_bmfile)

bbp_ng/OP_EXPORT_virtools.py

@@ -0,0 +1,552 @@
+import bpy, mathutils
+from bpy_extras.wm_utils.progress_report import ProgressReport
+import tempfile, os, typing
+from . import PROP_preferences, UTIL_ioport_shared
+from . import UTIL_virtools_types, UTIL_functions, UTIL_file_browser, UTIL_blender_mesh, UTIL_ballance_texture, UTIL_naming_convension
+from . import PROP_virtools_group, PROP_virtools_material, PROP_virtools_mesh, PROP_virtools_texture, PROP_virtools_light
+from .PyBMap import bmap_wrapper as bmap
+
+class BBP_OT_export_virtools(bpy.types.Operator, UTIL_file_browser.ExportVirtoolsFile, UTIL_ioport_shared.ExportParams, UTIL_ioport_shared.VirtoolsParams, UTIL_ioport_shared.BallanceParams):
+    """Export Virtools File"""
+    bl_idname = "bbp.export_virtools"
+    bl_label = "Export Virtools File"
+    bl_options = {'PRESET'}
+    bl_translation_context = 'BBP_OT_export_virtools'
+
+    @classmethod
+    def poll(cls, context):
+        return (
+            PROP_preferences.get_raw_preferences().has_valid_blc_tex_folder()
+            and bmap.is_bmap_available())
+    
+    def execute(self, context):
+        # check selecting first
+        objls: tuple[bpy.types.Object] | None = self.general_get_export_objects(context)
+        if objls is None:
+            self.report({'ERROR'}, 'No selected target!')
+            return {'CANCELLED'}
+
+        # check texture save option to avoid real stupid user.
+        texture_save_opt = self.general_get_texture_save_opt()
+        if texture_save_opt == UTIL_virtools_types.CK_TEXTURE_SAVEOPTIONS.CKTEXTURE_USEGLOBAL:
+            self.report({'ERROR'}, 'You can not specify "Use Global" as global texture save option!')
+            return {'CANCELLED'}
+
+        # check whether encoding list is empty to avoid real stupid user.
+        encodings = self.general_get_vt_encodings(context)
+        if len(encodings) == 0:
+            self.report({'ERROR'}, 'You must specify at least one encoding for file saving (e.g. cp1252, gbk)!')
+            return {'CANCELLED'}
+
+        # start exporting
+        with UTIL_ioport_shared.ExportEditModeBackup() as editmode_guard:
+            _export_virtools(
+                self.general_get_filename(),
+                encodings,
+                texture_save_opt,
+                self.general_get_use_compress(),
+                self.general_get_compress_level(),
+                self.general_get_successive_sector(),
+                self.general_get_successive_sector_count(),
+                objls
+            )
+
+        self.report({'INFO'}, "Virtools File Exporting Finished.")
+        return {'FINISHED'}
+    
+    def draw(self, context):
+        layout = self.layout
+        self.draw_export_params(context, layout)
+        self.draw_virtools_params(context, layout, False)
+        self.draw_ballance_params(layout, False)
+
+_TObj3dPair = tuple[bpy.types.Object, bmap.BM3dObject]
+_TLightPair = tuple[bpy.types.Object, bpy.types.Light, bmap.BMTargetLight]
+_TMeshPair = tuple[bpy.types.Object, bpy.types.Mesh, bmap.BMMesh]
+_TMaterialPair = tuple[bpy.types.Material, bmap.BMMaterial]
+_TTexturePair = tuple[bpy.types.Image, bmap.BMTexture]
+
+def _export_virtools(
+        file_name_: str, 
+        encodings_: tuple[str], 
+        texture_save_opt_: UTIL_virtools_types.CK_TEXTURE_SAVEOPTIONS,
+        use_compress_: bool,
+        compress_level_: int, 
+        successive_sector_: bool,
+        successive_sector_count_: int,
+        export_objects: tuple[bpy.types.Object, ...]
+    ) -> None:
+
+    # create temp folder
+    with tempfile.TemporaryDirectory() as vt_temp_folder:
+        tr_text: str = bpy.app.translations.pgettext_rpt(
+            'Virtools Engine Temporary Directory: {0}', 'BBP_OT_export_virtools/execute')
+        print(tr_text.format(vt_temp_folder))
+
+        # create virtools reader context
+        with bmap.BMFileWriter(
+            vt_temp_folder,
+            PROP_preferences.get_raw_preferences().mBallanceTextureFolder,
+            encodings_) as writer:
+
+            # prepare progress reporter
+            with ProgressReport(wm = bpy.context.window_manager) as progress:
+                # prepare 3dobject and light
+                obj3d_crets: tuple[_TObj3dPair, ...]
+                light_crets: tuple[_TLightPair, ...]
+                (obj3d_crets, light_crets) = _prepare_virtools_3dobjects(writer, progress, export_objects)
+                # export group according to prepared 3dobject
+                _export_virtools_groups(writer, progress, successive_sector_, successive_sector_count_, obj3d_crets)
+                # export prepared light
+                _export_virtools_light(writer, progress, light_crets)
+                # export prepared 3dobject
+                mesh_crets: tuple[_TMeshPair, ...] = _export_virtools_3dobjects(
+                    writer, progress, obj3d_crets)
+                # export mesh
+                material_crets: tuple[_TMaterialPair, ...] = _export_virtools_meshes(
+                    writer, progress, mesh_crets)
+                # export material
+                texture_crets: tuple[_TTexturePair, ...] = _export_virtools_materials(
+                    writer, progress, material_crets)
+                # export texture
+                _export_virtools_textures(writer, progress, vt_temp_folder, texture_crets)
+
+                # save document
+                _save_virtools_document(
+                    writer, progress, file_name_, texture_save_opt_, use_compress_, compress_level_)
+
+def _prepare_virtools_3dobjects(
+        writer: bmap.BMFileWriter,
+        progress: ProgressReport,
+        export_objects: tuple[bpy.types.Object, ...]
+        ) -> tuple[tuple[_TObj3dPair, ...], tuple[_TLightPair, ...]]:
+    # this function only create equvalent entries in virtools engine and do not export anything
+    # because _export_virtools_3dobjects() and _export_virtools_groups() are need use the return value of this function
+    # 
+    # at the same time, due to the difference of light object between virtools and blender,
+    # we also need extract exported lights and create equvalent entries in virtools for them.
+
+    # create 3dobject hashset and result
+    obj3d_crets: list[_TObj3dPair] = []
+    obj3d_cret_set: set[bpy.types.Object] = set()
+    # create light hashset and result
+    light_crets: list[_TLightPair] = []
+    light_cret_set: set[bpy.types.Object] = set()
+    # start saving
+    tr_text: str = bpy.app.translations.pgettext_rpt('Creating 3dObjects and Lights', 'BBP_OT_export_virtools/execute')
+    progress.enter_substeps(len(export_objects), tr_text)
+
+    # iterate exported object list
+    for obj3d in export_objects:
+        # only accept mesh object and light object
+        # all of other objects will be discard.
+        match(obj3d.type):
+            case 'MESH':
+                # mesh object
+                if obj3d not in obj3d_cret_set:
+                    # add into set
+                    obj3d_cret_set.add(obj3d)
+                    # create virtools instance
+                    vtobj3d: bmap.BM3dObject = writer.create_3dobject()
+                    # add into result list
+                    obj3d_crets.append((obj3d, vtobj3d))
+            case 'LIGHT':
+                # light object
+                if obj3d not in light_cret_set:
+                    # add into set
+                    light_cret_set.add(obj3d)
+                    # create virtools instance
+                    vtlight: bmap.BMTargetLight = writer.create_target_light()
+                    # add into result list
+                    light_crets.append((obj3d, typing.cast(bpy.types.Light, obj3d.data), vtlight))
+        
+        # step progress no matter whether create new one
+        progress.step()
+
+    # leave progress and return
+    progress.leave_substeps()
+    return (tuple(obj3d_crets), tuple(light_crets))
+
+def _export_virtools_groups(
+        writer: bmap.BMFileWriter,
+        progress: ProgressReport,
+        successive_sector: bool,
+        successive_sector_count: int,
+        obj3d_crets: tuple[_TObj3dPair, ...]
+        ) -> None:
+    # create virtools group
+    group_cret_map: dict[str, bmap.BMGroup] = {}
+    # start saving
+    tr_text: str = bpy.app.translations.pgettext_rpt('Saving Groups', 'BBP_OT_export_virtools/execute')
+    progress.enter_substeps(len(obj3d_crets), tr_text)
+
+    # create sector group first if user ordered
+    # This step is designed for ensure that the created sector group is successive.
+    # 
+    # Due to the design of Ballance, Ballance rely on checking the existance of Sector_XX to get how many sectors this map have.
+    # Thus if there are no component in a sector, it still need to create a empty Sector_XX group, otherwise the game will crash
+    # or be ended at a accident sector.
+    # 
+    # So we create all needed sector group in here to make sure exported virtools file can be read by Ballancde correctly.
+    if successive_sector:
+        for i in range(successive_sector_count):
+            gp_name: str = UTIL_naming_convension.build_name_from_sector_index(i + 1)
+            vtgroup: bmap.BMGroup | None = group_cret_map.get(gp_name, None)
+            if vtgroup is None:
+                vtgroup = writer.create_group()
+                vtgroup.set_name(gp_name)
+                group_cret_map[gp_name] = vtgroup
+
+    for obj3d, vtobj3d in obj3d_crets:
+        # open group visitor
+        with PROP_virtools_group.VirtoolsGroupsHelper(obj3d) as gp_visitor:
+            for gp_name in gp_visitor.iterate_groups():
+                # get group or create new group from guard
+                vtgroup: bmap.BMGroup | None = group_cret_map.get(gp_name, None)
+                if vtgroup is None:
+                    vtgroup = writer.create_group()
+                    vtgroup.set_name(gp_name)
+                    group_cret_map[gp_name] = vtgroup
+                
+                # group this object
+                vtgroup.add_object(vtobj3d)
+
+        # leave group visitor and step
+        progress.step()
+
+    # leave progress and return
+    progress.leave_substeps()
+
+def _export_virtools_light(
+        writer: bmap.BMFileWriter,
+        progress: ProgressReport,
+        light_crets: tuple[_TLightPair, ...]
+        ) -> None:
+    # start saving
+    tr_text: str = bpy.app.translations.pgettext_rpt('Saving Lights', 'BBP_OT_export_virtools/execute')
+    progress.enter_substeps(len(light_crets), tr_text)
+    
+    for obj3d, light, vtlight in light_crets:
+        # set name
+        vtlight.set_name(obj3d.name)
+
+        # setup 3d entity parts
+        # set world matrix
+        vtmat: UTIL_virtools_types.VxMatrix = UTIL_virtools_types.VxMatrix()
+        bldmat: mathutils.Matrix = UTIL_virtools_types.bldmatrix_restore_light_obj(obj3d.matrix_world)
+        UTIL_virtools_types.vxmatrix_from_blender(vtmat, bldmat)
+        UTIL_virtools_types.vxmatrix_conv_co(vtmat)
+        vtlight.set_world_matrix(vtmat)
+        # set visibility
+        vtlight.set_visibility(not obj3d.hide_get())
+
+        # setup light data
+        rawlight: PROP_virtools_light.RawVirtoolsLight = PROP_virtools_light.get_raw_virtools_light(light)
+
+        vtlight.set_type(rawlight.mType)
+        vtlight.set_color(rawlight.mColor)
+
+        vtlight.set_constant_attenuation(rawlight.mConstantAttenuation)
+        vtlight.set_linear_attenuation(rawlight.mLinearAttenuation)
+        vtlight.set_quadratic_attenuation(rawlight.mQuadraticAttenuation)
+
+        vtlight.set_range(rawlight.mRange)
+
+        vtlight.set_hot_spot(rawlight.mHotSpot)
+        vtlight.set_falloff(rawlight.mFalloff)
+        vtlight.set_falloff_shape(rawlight.mFalloffShape)
+
+        # step
+        progress.step()
+
+    # leave progress and return
+    progress.leave_substeps()
+
+def _export_virtools_3dobjects(
+        writer: bmap.BMFileWriter,
+        progress: ProgressReport,
+        obj3d_crets: tuple[_TObj3dPair, ...]
+        ) -> tuple[_TMeshPair, ...]:
+    # create virtools mesh
+    mesh_crets: list[_TMeshPair] = []
+    mesh_cret_map: dict[bpy.types.Mesh, bmap.BMMesh] = {}
+    # start saving
+    tr_text: str = bpy.app.translations.pgettext_rpt('Saving 3dObjects', 'BBP_OT_export_virtools/execute')
+    progress.enter_substeps(len(obj3d_crets), tr_text)
+
+    for obj3d, vtobj3d in obj3d_crets:
+        # set name
+        vtobj3d.set_name(obj3d.name)
+
+        # check mesh
+        mesh: bpy.types.Mesh | None = typing.cast(bpy.types.Mesh | None, obj3d.data)
+        if mesh is not None:
+            # get existing vt mesh or create new one
+            vtmesh: bmap.BMMesh | None = mesh_cret_map.get(mesh, None)
+            if vtmesh is None:
+                vtmesh = writer.create_mesh()
+                mesh_crets.append((obj3d, mesh, vtmesh))
+                mesh_cret_map[mesh] = vtmesh
+
+            # assign mesh
+            vtobj3d.set_current_mesh(vtmesh)
+        else:
+            vtobj3d.set_current_mesh(None)
+
+        # set world matrix
+        vtmat: UTIL_virtools_types.VxMatrix = UTIL_virtools_types.VxMatrix()
+        UTIL_virtools_types.vxmatrix_from_blender(vtmat, obj3d.matrix_world)
+        UTIL_virtools_types.vxmatrix_conv_co(vtmat)
+        vtobj3d.set_world_matrix(vtmat)
+
+        # set visibility
+        vtobj3d.set_visibility(not obj3d.hide_get())
+
+        # step
+        progress.step()
+
+    # leave progress and return
+    progress.leave_substeps()
+    return tuple(mesh_crets)
+
+def _export_virtools_meshes(
+        writer: bmap.BMFileWriter,
+        progress: ProgressReport,
+        mesh_crets: tuple[_TMeshPair, ...]
+        ) -> tuple[_TMaterialPair, ...]:
+    # create virtools mesh
+    material_crets: list[_TMaterialPair] = []
+    material_cret_map: dict[bpy.types.Material, bmap.BMMaterial] = {}
+    # start saving
+    tr_text: str = bpy.app.translations.pgettext_rpt('Saving Meshes', 'BBP_OT_export_virtools/execute')
+    progress.enter_substeps(len(mesh_crets), tr_text)
+
+    # iterate meshes
+    for obj3d, mesh, vtmesh in mesh_crets:
+        # we need use temporary mesh function to visit triangulated meshes
+        # so we ignore mesh factor and use obj3d to create temp mesh to get data
+        # open temp mesh helper
+        with UTIL_blender_mesh.TemporaryMesh(obj3d) as tempmesh:
+            # sync mesh name, lit mode
+            vtmesh.set_name(mesh.name)
+            mesh_settings: PROP_virtools_mesh.RawVirtoolsMesh = PROP_virtools_mesh.get_raw_virtools_mesh(mesh)
+            vtmesh.set_lit_mode(mesh_settings.mLitMode)
+
+            # sync mesh main data
+            # open mesh visitor
+            with UTIL_blender_mesh.MeshReader(tempmesh.get_temp_mesh()) as mesh_visitor:
+                # construct data provider
+                def pos_iterator() -> typing.Iterator[UTIL_virtools_types.VxVector3]:
+                    for v in mesh_visitor.get_vertex_position():
+                        UTIL_virtools_types.vxvector3_conv_co(v)
+                        yield v
+                def nml_iterator() -> typing.Iterator[UTIL_virtools_types.VxVector3]:
+                    for v in mesh_visitor.get_vertex_normal():
+                        UTIL_virtools_types.vxvector3_conv_co(v)
+                        yield v
+                def uv_iterator() -> typing.Iterator[UTIL_virtools_types.VxVector2]:
+                    for v in mesh_visitor.get_vertex_uv():
+                        UTIL_virtools_types.vxvector2_conv_co(v)
+                        yield v
+
+                # construct mtl slot
+                def mtl_iterator() -> typing.Iterator[bmap.BMMaterial | None]:
+                    for mtl in mesh_visitor.get_material_slot():
+                        if mtl is None: yield None
+                        else:
+                            # get existing one or create new one
+                            vtmaterial: bmap.BMMaterial | None = material_cret_map.get(mtl, None)
+                            if vtmaterial is None:
+                                vtmaterial = writer.create_material()
+                                material_crets.append((mtl, vtmaterial))
+                                material_cret_map[mtl] = vtmaterial
+                            # yield data
+                            yield vtmaterial
+
+                def face_idx_iterator(idx_type: int) -> typing.Iterator[UTIL_virtools_types.CKFaceIndices]:
+                    data: UTIL_virtools_types.CKFaceIndices = UTIL_virtools_types.CKFaceIndices()
+                    for fidx in mesh_visitor.get_face():
+                        # swap indices
+                        fidx.conv_co()
+                        # set data by specific index
+                        match(idx_type):
+                            case 0:  data.i1, data.i2, data.i3 = fidx.mIndices[0].mPosIdx, fidx.mIndices[1].mPosIdx, fidx.mIndices[2].mPosIdx
+                            case 1:  data.i1, data.i2, data.i3 = fidx.mIndices[0].mNmlIdx, fidx.mIndices[1].mNmlIdx, fidx.mIndices[2].mNmlIdx
+                            case 2:  data.i1, data.i2, data.i3 = fidx.mIndices[0].mUvIdx, fidx.mIndices[1].mUvIdx, fidx.mIndices[2].mUvIdx
+                            case _: raise UTIL_functions.BBPException('invalid index type.')
+                        # yield data
+                        yield data
+                def face_mtl_iterator() -> typing.Iterator[int]:
+                    for fidx in mesh_visitor.get_face():
+                        yield fidx.mMtlIdx
+                
+                # create virtools mesh transition
+                # and write into mesh
+                with bmap.BMMeshTrans() as mesh_trans:
+                    # prepare vertices
+                    mesh_trans.prepare_vertex(
+                        mesh_visitor.get_vertex_position_count(),
+                        pos_iterator()
+                    )
+                    mesh_trans.prepare_normal(
+                        mesh_visitor.get_vertex_normal_count(),
+                        nml_iterator()
+                    )
+                    mesh_trans.prepare_uv(
+                        mesh_visitor.get_vertex_uv_count(),
+                        uv_iterator()
+                    )
+                    # prepare mtl slots
+                    mesh_trans.prepare_mtl_slot(
+                        mesh_visitor.get_material_slot_count(),
+                        mtl_iterator()
+                    )
+                    # prepare face
+                    mesh_trans.prepare_face(
+                        mesh_visitor.get_face_count(),
+                        face_idx_iterator(0),
+                        face_idx_iterator(1),
+                        face_idx_iterator(2),
+                        face_mtl_iterator()
+                    )
+
+                    # parse to vtmesh
+                    mesh_trans.parse(vtmesh)
+
+                # end of mesh trans
+            # end of mesh visitor
+        # end of temp mesh
+
+        # step
+        progress.step()
+
+    # leave progress and return
+    progress.leave_substeps()
+    return tuple(material_crets)
+
+def _export_virtools_materials(
+        writer: bmap.BMFileWriter,
+        progress: ProgressReport,
+        material_crets: tuple[_TMaterialPair, ...]
+        ) -> tuple[_TTexturePair, ...]:
+    # create virtools mesh
+    texture_crets: list[_TTexturePair] = []
+    texture_cret_map: dict[bpy.types.Image, bmap.BMTexture] = {}
+    # start saving
+    tr_text: str = bpy.app.translations.pgettext_rpt('Saving Materials', 'BBP_OT_export_virtools/execute')
+    progress.enter_substeps(len(material_crets), tr_text)
+
+    for mtl, vtmaterial in material_crets:
+        # set name
+        vtmaterial.set_name(mtl.name)
+
+        # get raw mtl
+        rawmtl: PROP_virtools_material.RawVirtoolsMaterial = PROP_virtools_material.get_raw_virtools_material(mtl)
+
+        # apply vt material
+        vtmaterial.set_diffuse(rawmtl.mDiffuse)
+        vtmaterial.set_ambient(rawmtl.mAmbient)
+        vtmaterial.set_specular(rawmtl.mSpecular)
+        vtmaterial.set_emissive(rawmtl.mEmissive)
+        vtmaterial.set_specular_power(rawmtl.mSpecularPower)
+
+        # apply assoc texture
+        if rawmtl.mTexture is not None:
+            # create or get new one vt texture
+            vttexture: bmap.BMTexture | None = texture_cret_map.get(rawmtl.mTexture, None)
+            if vttexture is None:
+                vttexture = writer.create_texture()
+                texture_cret_map[rawmtl.mTexture] = vttexture
+                texture_crets.append((rawmtl.mTexture, vttexture))
+            # assign texture
+            vtmaterial.set_texture(vttexture)
+        else:
+            vtmaterial.set_texture(None)
+        
+        vtmaterial.set_texture_border_color(rawmtl.mTextureBorderColor)
+
+        vtmaterial.set_texture_blend_mode(rawmtl.mTextureBlendMode)
+        vtmaterial.set_texture_min_mode(rawmtl.mTextureMinMode)
+        vtmaterial.set_texture_mag_mode(rawmtl.mTextureMagMode)
+        vtmaterial.set_texture_address_mode(rawmtl.mTextureAddressMode)
+
+        vtmaterial.set_source_blend(rawmtl.mSourceBlend)
+        vtmaterial.set_dest_blend(rawmtl.mDestBlend)
+        vtmaterial.set_fill_mode(rawmtl.mFillMode)
+        vtmaterial.set_shade_mode(rawmtl.mShadeMode)
+
+        vtmaterial.set_alpha_test_enabled(rawmtl.mEnableAlphaTest)
+        vtmaterial.set_alpha_blend_enabled(rawmtl.mEnableAlphaBlend)
+        vtmaterial.set_perspective_correction_enabled(rawmtl.mEnablePerspectiveCorrection)
+        vtmaterial.set_z_write_enabled(rawmtl.mEnableZWrite)
+        vtmaterial.set_two_sided_enabled(rawmtl.mEnableTwoSided)
+
+        vtmaterial.set_alpha_ref(rawmtl.mAlphaRef)
+        vtmaterial.set_alpha_func(rawmtl.mAlphaFunc)
+        vtmaterial.set_z_func(rawmtl.mZFunc)
+
+        # step
+        progress.step()
+
+    # leave progress and return
+    progress.leave_substeps()
+    return tuple(texture_crets)
+
+def _export_virtools_textures(
+        writer: bmap.BMFileWriter,
+        progress: ProgressReport,
+        vt_temp_folder: str,
+        texture_crets: tuple[_TTexturePair, ...]
+        ) -> None:
+    # start saving
+    tr_text: str = bpy.app.translations.pgettext_rpt('Saving Textures', 'BBP_OT_export_virtools/execute')
+    progress.enter_substeps(len(texture_crets), tr_text)
+
+    for tex, vttexture in texture_crets:
+        # set name
+        vttexture.set_name(tex.name)
+
+        # set texture cfg
+        rawtex: PROP_virtools_texture.RawVirtoolsTexture = PROP_virtools_texture.get_raw_virtools_texture(tex)
+        vttexture.set_save_options(rawtex.mSaveOptions)
+        vttexture.set_video_format(rawtex.mVideoFormat)
+
+        # save core texture
+        # load ballance textures to vt engine from external ref path
+        # load other textures to vt engine from temp folder.
+        # no need to distinguish save options
+        try_filepath: str | None = UTIL_ballance_texture.get_ballance_texture_filename(
+            UTIL_ballance_texture.get_texture_filepath(tex))
+        if try_filepath is None:
+            # non-ballance file, save in temp and change file path to point to it.
+            try_filepath = UTIL_ballance_texture.generate_other_texture_save_path(tex, vt_temp_folder)
+            UTIL_ballance_texture.save_other_texture(tex, try_filepath)
+        # load into vt engine
+        vttexture.load_image(try_filepath)
+
+        # step
+        progress.step()
+
+    # leave progress and return
+    progress.leave_substeps()
+
+def _save_virtools_document(
+        writer: bmap.BMFileWriter,
+        progress: ProgressReport,
+        file_name: str,
+        texture_save_opt: UTIL_virtools_types.CK_TEXTURE_SAVEOPTIONS,
+        use_compress: bool,
+        compress_level: int
+        ) -> None:
+    
+    tr_text: str = bpy.app.translations.pgettext_rpt('Saving Document', 'BBP_OT_export_virtools/execute')
+    progress.enter_substeps(1, tr_text)
+    writer.save(file_name, texture_save_opt, use_compress, compress_level)
+    progress.step()
+    progress.leave_substeps()
+    
+def register() -> None:
+    bpy.utils.register_class(BBP_OT_export_virtools)
+
+def unregister() -> None:
+    bpy.utils.unregister_class(BBP_OT_export_virtools)

bbp_ng/OP_IMPORT_bmfile.py

@@ -0,0 +1,28 @@
+import bpy
+from . import PROP_preferences, UTIL_functions, UTIL_file_browser, UTIL_blender_mesh, UTIL_ioport_shared
+
+class BBP_OT_import_bmfile(bpy.types.Operator, UTIL_file_browser.ImportBmxFile, UTIL_ioport_shared.ImportParams):
+    """Load a Ballance Map File (BM File Spec 1.4)"""
+    bl_idname = "bbp.import_bmfile"
+    bl_label = "Import BM (Ballance Map) File"
+    bl_options = {'PRESET', 'UNDO'}
+    bl_translation_context = 'BBP_OT_import_bmfile'
+    
+    @classmethod
+    def poll(cls, context):
+        return PROP_preferences.get_raw_preferences().has_valid_blc_tex_folder()
+    
+    def execute(self, context):
+        self.report({'ERROR'}, 'This feature is not supported yet.')
+        # self.report({'INFO'}, "BM File Importing Finished.")
+        return {'FINISHED'}
+    
+    def draw(self, context):
+        layout = self.layout
+        self.draw_import_params(layout.box())
+
+def register() -> None:
+    bpy.utils.register_class(BBP_OT_import_bmfile)
+
+def unregister() -> None:
+    bpy.utils.unregister_class(BBP_OT_import_bmfile)

bbp_ng/OP_IMPORT_virtools.py

@@ -0,0 +1,485 @@
+import bpy, mathutils
+from bpy_extras.wm_utils.progress_report import ProgressReport
+import tempfile, os, typing
+from . import PROP_preferences, UTIL_ioport_shared
+from . import UTIL_virtools_types, UTIL_functions, UTIL_file_browser, UTIL_blender_mesh, UTIL_ballance_texture, UTIL_naming_convension
+from . import PROP_virtools_group, PROP_virtools_material, PROP_virtools_mesh, PROP_virtools_texture, PROP_virtools_light, PROP_ballance_map_info
+from .PyBMap import bmap_wrapper as bmap
+
+class BBP_OT_import_virtools(bpy.types.Operator, UTIL_file_browser.ImportVirtoolsFile, UTIL_ioport_shared.ImportParams, UTIL_ioport_shared.VirtoolsParams, UTIL_ioport_shared.BallanceParams):
+    """Import Virtools File"""
+    bl_idname = "bbp.import_virtools"
+    bl_label = "Import Virtools File"
+    bl_options = {'PRESET', 'UNDO'}
+    bl_translation_context = 'BBP_OT_import_virtools'
+
+    @classmethod
+    def poll(cls, context):
+        return (
+            PROP_preferences.get_raw_preferences().has_valid_blc_tex_folder()
+            and bmap.is_bmap_available())
+    
+    def execute(self, context):
+        # check whether encoding list is empty to avoid real stupid user.
+        encodings = self.general_get_vt_encodings(context)
+        if len(encodings) == 0:
+            self.report({'ERROR'}, 'You must specify at least one encoding for file loading (e.g. cp1252, gbk)!')
+            return {'CANCELLED'}
+
+        _import_virtools(
+            self.general_get_filename(),
+            encodings,
+            self.general_get_conflict_resolver()
+        )
+        self.report({'INFO'}, "Virtools File Importing Finished.")
+        return {'FINISHED'}
+    
+    def draw(self, context):
+        layout = self.layout
+        self.draw_import_params(layout)
+        self.draw_virtools_params(context, layout, True)
+        self.draw_ballance_params(layout, True)
+
+def _import_virtools(file_name_: str, encodings_: tuple[str], resolver: UTIL_ioport_shared.ConflictResolver) -> None:
+    # create temp folder
+    with tempfile.TemporaryDirectory() as vt_temp_folder:
+        tr_text: str = bpy.app.translations.pgettext_rpt(
+            'Virtools Engine Temporary Directory: {0}', 'BBP_OT_import_virtools/execute')
+        print(tr_text.format(vt_temp_folder))
+
+        # create virtools reader context
+        with bmap.BMFileReader(
+            file_name_, 
+            vt_temp_folder,
+            PROP_preferences.get_raw_preferences().mBallanceTextureFolder,
+            encodings_) as reader:
+
+            # prepare progress reporter
+            with ProgressReport(wm = bpy.context.window_manager) as progress:
+                # import textures
+                texture_cret_map: dict[bmap.BMTexture, bpy.types.Image] = _import_virtools_textures(
+                    reader, progress, resolver)
+                # import materials
+                material_cret_map: dict[bmap.BMMaterial, bpy.types.Material] = _import_virtools_materials(
+                    reader, progress, resolver, texture_cret_map)
+                # import meshes
+                mesh_cret_map: dict[bmap.BMMesh, bpy.types.Mesh] = _import_virtools_meshes(
+                    reader, progress, resolver, material_cret_map)
+                # import 3dobjects
+                obj3d_cret_map: dict[bmap.BM3dObject, bpy.types.Object] = _import_virtools_3dobjects(
+                    reader, progress, resolver, mesh_cret_map)
+                # import light
+                _import_virtools_lights(reader, progress, resolver)
+                # import groups
+                _import_virtools_groups(reader, progress, obj3d_cret_map)
+
+def _import_virtools_textures(
+        reader: bmap.BMFileReader, 
+        progress: ProgressReport,
+        resolver: UTIL_ioport_shared.ConflictResolver
+        ) -> dict[bmap.BMTexture, bpy.types.Image]:
+    # create map
+    texture_cret_map: dict[bmap.BMTexture, bpy.types.Image] = {}
+    # notify steps
+    tr_text: str = bpy.app.translations.pgettext_rpt('Loading Textures', 'BBP_OT_import_virtools/execute')
+    progress.enter_substeps(reader.get_texture_count(), tr_text)
+
+    # create another temp folder for raw data virtools texture importing
+    with tempfile.TemporaryDirectory() as rawdata_temp:
+        tr_text = bpy.app.translations.pgettext_rpt(
+            'Texture Raw Data Temporary Directory: {0}', 'BBP_OT_import_virtools/execute')
+        print(tr_text.format(rawdata_temp))
+
+        for vttexture in reader.get_textures():
+            tex_cret: typing.Callable[[], bpy.types.Image]
+            texpath_to_load: str | None = vttexture.get_file_name()
+
+            # if no assoc file path (what? but it is real happended)
+            # this is invalid image, create a blank image instead
+            if texpath_to_load is None:
+                tex_cret = lambda: bpy.data.images.new("", 1, 1)
+            else:
+                # if this image is raw data, save it in external folder before loading
+                # the attribute of raw data saving is the file path is not absolute path
+                if not os.path.isabs(texpath_to_load):
+                    texpath_to_load = os.path.join(
+                        rawdata_temp,
+                        os.path.basename(texpath_to_load)
+                    )
+                    vttexture.save_image(texpath_to_load)
+
+                # detect whether it is ballance texture and load
+                try_blc_tex: str | None = UTIL_ballance_texture.get_ballance_texture_filename(texpath_to_load)
+                
+                if try_blc_tex is not None:
+                    # load as ballance texture
+                    tex_cret = lambda: UTIL_ballance_texture.load_ballance_texture(typing.cast(str, try_blc_tex))
+                else:
+                    # load as other textures
+                    tex_cret = lambda: UTIL_ballance_texture.load_other_texture(typing.cast(str, texpath_to_load))
+
+            # create real texture by tex cret fct
+            (tex, init_tex) = resolver.create_texture(
+                UTIL_virtools_types.virtools_name_regulator(vttexture.get_name()), 
+                tex_cret
+            )
+            
+            # init tex if needed
+            if init_tex:
+                # set texture cfg
+                rawtex: PROP_virtools_texture.RawVirtoolsTexture = PROP_virtools_texture.RawVirtoolsTexture()
+                rawtex.mSaveOptions = vttexture.get_save_options()
+                rawtex.mVideoFormat = vttexture.get_video_format()
+                PROP_virtools_texture.set_raw_virtools_texture(tex, rawtex)
+
+            # insert it to map
+            texture_cret_map[vttexture] = tex
+
+            # inc steps
+            progress.step()
+
+    # leave progress and return map
+    progress.leave_substeps()
+    return texture_cret_map
+    
+def _import_virtools_materials(
+        reader: bmap.BMFileReader, 
+        progress: ProgressReport,
+        resolver: UTIL_ioport_shared.ConflictResolver,
+        texture_cret_map: dict[bmap.BMTexture, bpy.types.Image]
+        ) -> dict[bmap.BMMaterial, bpy.types.Material]:
+    # create map and prepare progress
+    material_cret_map: dict[bmap.BMMaterial, bpy.types.Material] = {}
+    # notify steps
+    tr_text: str = bpy.app.translations.pgettext_rpt('Loading Materials', 'BBP_OT_import_virtools/execute')
+    progress.enter_substeps(reader.get_material_count(), tr_text)
+
+    for vtmaterial in reader.get_materials():
+        # create mtl
+        (mtl, init_mtl) = resolver.create_material(
+            UTIL_virtools_types.virtools_name_regulator(vtmaterial.get_name())
+        )
+
+        # apply it if necessary
+        if init_mtl:
+            # create new raw material
+            rawmtl: PROP_virtools_material.RawVirtoolsMaterial = PROP_virtools_material.RawVirtoolsMaterial()
+            
+            rawmtl.mDiffuse = vtmaterial.get_diffuse()
+            rawmtl.mAmbient = vtmaterial.get_ambient()
+            rawmtl.mSpecular = vtmaterial.get_specular()
+            rawmtl.mEmissive = vtmaterial.get_emissive()
+            rawmtl.mSpecularPower = vtmaterial.get_specular_power()
+
+            mtltex: bmap.BMTexture | None = vtmaterial.get_texture()
+            if mtltex:
+                rawmtl.mTexture = texture_cret_map.get(mtltex, None)
+            else:
+                rawmtl.mTexture = None
+            rawmtl.mTextureBorderColor = vtmaterial.get_texture_border_color()
+
+            rawmtl.mTextureBlendMode = vtmaterial.get_texture_blend_mode()
+            rawmtl.mTextureMinMode = vtmaterial.get_texture_min_mode()
+            rawmtl.mTextureMagMode = vtmaterial.get_texture_mag_mode()
+            rawmtl.mTextureAddressMode = vtmaterial.get_texture_address_mode()
+
+            rawmtl.mSourceBlend = vtmaterial.get_source_blend()
+            rawmtl.mDestBlend = vtmaterial.get_dest_blend()
+            rawmtl.mFillMode = vtmaterial.get_fill_mode()
+            rawmtl.mShadeMode = vtmaterial.get_shade_mode()
+
+            rawmtl.mEnableAlphaTest = vtmaterial.get_alpha_test_enabled()
+            rawmtl.mEnableAlphaBlend = vtmaterial.get_alpha_blend_enabled()
+            rawmtl.mEnablePerspectiveCorrection = vtmaterial.get_perspective_correction_enabled()
+            rawmtl.mEnableZWrite = vtmaterial.get_z_write_enabled()
+            rawmtl.mEnableTwoSided = vtmaterial.get_two_sided_enabled()
+
+            rawmtl.mAlphaRef = vtmaterial.get_alpha_ref()
+            rawmtl.mAlphaFunc = vtmaterial.get_alpha_func()
+            rawmtl.mZFunc = vtmaterial.get_z_func()
+
+            PROP_virtools_material.set_raw_virtools_material(mtl, rawmtl)
+            PROP_virtools_material.apply_to_blender_material(mtl)
+
+        # add into map and step
+        material_cret_map[vtmaterial] = mtl
+        progress.step()
+
+    # leave progress and return
+    progress.leave_substeps()
+    return material_cret_map
+
+def _import_virtools_meshes(
+        reader: bmap.BMFileReader, 
+        progress: ProgressReport,
+        resolver: UTIL_ioport_shared.ConflictResolver, 
+        material_cret_map: dict[bmap.BMMaterial, bpy.types.Material]
+        ) -> dict[bmap.BMMesh, bpy.types.Mesh]:
+    # create map and prepare progress
+    mesh_cret_map: dict[bmap.BMMesh, bpy.types.Mesh] = {}
+    # notify steps
+    tr_text: str = bpy.app.translations.pgettext_rpt('Loading Meshes', 'BBP_OT_import_virtools/execute')
+    progress.enter_substeps(reader.get_mesh_count(), tr_text)
+
+    for vtmesh in reader.get_meshs():
+        # create mesh
+        (mesh, init_mesh) = resolver.create_mesh(
+            UTIL_virtools_types.virtools_name_regulator(vtmesh.get_name())
+        )
+
+        # set mesh data if necessary
+        if init_mesh:
+            # open mesh writer
+            with UTIL_blender_mesh.MeshWriter(mesh) as meshoper:
+                # construct data provider
+                data_prov: UTIL_blender_mesh.MeshWriterIngredient = UTIL_blender_mesh.MeshWriterIngredient()
+
+                # constructor data itor
+                def pos_iterator() -> typing.Iterator[UTIL_virtools_types.VxVector3]:
+                    for v in vtmesh.get_vertex_positions():
+                        UTIL_virtools_types.vxvector3_conv_co(v)
+                        yield v
+                def nml_iterator() -> typing.Iterator[UTIL_virtools_types.VxVector3]:
+                    for v in vtmesh.get_vertex_normals():
+                        UTIL_virtools_types.vxvector3_conv_co(v)
+                        yield v
+                def uv_iterator() -> typing.Iterator[UTIL_virtools_types.VxVector2]:
+                    for v in vtmesh.get_vertex_uvs():
+                        UTIL_virtools_types.vxvector2_conv_co(v)
+                        yield v
+                def face_iterator() -> typing.Iterator[UTIL_blender_mesh.FaceData]:
+                    face: UTIL_blender_mesh.FaceData = UTIL_blender_mesh.FaceData(
+                        [UTIL_blender_mesh.FaceVertexData() for i in range(3)]
+                    )
+
+                    findices_itor = vtmesh.get_face_indices()
+                    fmtl_itor = vtmesh.get_face_material_slot_indexs()
+                    for _ in range(vtmesh.get_face_count()):
+                        # set indices data
+                        vtindices = next(findices_itor)
+                        face.mIndices[0].mPosIdx = vtindices.i1
+                        face.mIndices[0].mNmlIdx = vtindices.i1
+                        face.mIndices[0].mUvIdx = vtindices.i1
+                        face.mIndices[1].mPosIdx = vtindices.i2
+                        face.mIndices[1].mNmlIdx = vtindices.i2
+                        face.mIndices[1].mUvIdx = vtindices.i2
+                        face.mIndices[2].mPosIdx = vtindices.i3
+                        face.mIndices[2].mNmlIdx = vtindices.i3
+                        face.mIndices[2].mUvIdx = vtindices.i3
+                        # swap indices
+                        face.conv_co()
+
+                        # set mtl data
+                        vtmtl = next(fmtl_itor)
+                        face.mMtlIdx = vtmtl
+
+                        # return
+                        yield face
+                def mtl_iterator() -> typing.Iterator[bpy.types.Material | None]:
+                    for vtmtl in vtmesh.get_material_slots():
+                        if vtmtl:
+                            yield material_cret_map.get(vtmtl, None)
+                        else:
+                            yield None
+
+                # assign to data provider
+                data_prov.mVertexPosition = pos_iterator()
+                data_prov.mVertexNormal = nml_iterator()
+                data_prov.mVertexUV = uv_iterator()
+                data_prov.mFace = face_iterator()
+                data_prov.mMaterial = mtl_iterator()
+
+                # add part
+                meshoper.add_ingredient(data_prov)
+
+            # end of mesh writer
+
+            # set other mesh settings
+            mesh_settings: PROP_virtools_mesh.RawVirtoolsMesh = PROP_virtools_mesh.RawVirtoolsMesh()
+            mesh_settings.mLitMode = vtmesh.get_lit_mode()
+            PROP_virtools_mesh.set_raw_virtools_mesh(mesh, mesh_settings)
+
+        # add into map and step
+        mesh_cret_map[vtmesh] = mesh
+        progress.step()
+
+    # leave progress and return
+    progress.leave_substeps()
+    return mesh_cret_map
+
+def _import_virtools_3dobjects(
+        reader: bmap.BMFileReader, 
+        progress: ProgressReport,
+        resolver: UTIL_ioport_shared.ConflictResolver, 
+        mesh_cret_map: dict[bmap.BMMesh, bpy.types.Mesh]
+        ) -> dict[bmap.BM3dObject, bpy.types.Object]:
+    # create map and prepare progress
+    obj3d_cret_map: dict[bmap.BM3dObject, bpy.types.Object] = {}
+    # notify steps
+    tr_text: str = bpy.app.translations.pgettext_rpt('Loading 3dObjects', 'BBP_OT_import_virtools/execute')
+    progress.enter_substeps(reader.get_3dobject_count(), tr_text)
+
+    for vt3dobj in reader.get_3dobjects():
+        # get virtools binding mesh data first
+        vt3dobj_data: bmap.BMMesh | None = vt3dobj.get_current_mesh()
+
+        # create 3d object with mesh
+        (obj3d, init_obj3d) = resolver.create_object(
+            UTIL_virtools_types.virtools_name_regulator(vt3dobj.get_name()),
+            None if vt3dobj_data is None else mesh_cret_map.get(vt3dobj_data, None)
+        )
+
+        # setup if necessary
+        if init_obj3d:
+            # add into scene
+            UTIL_functions.add_into_scene(obj3d)
+
+            # set world matrix
+            vtmat: UTIL_virtools_types.VxMatrix = vt3dobj.get_world_matrix()
+            UTIL_virtools_types.vxmatrix_conv_co(vtmat)
+            obj3d.matrix_world = UTIL_virtools_types.vxmatrix_to_blender(vtmat)
+
+            # set visibility
+            obj3d.hide_set(not vt3dobj.get_visibility())
+
+            # add into map
+            # NOTE: the return value only provided to group setter
+            # and group setter should only set group data to new created 3d objects
+            # thus we only insert pair when this 3d obj is new created.
+            obj3d_cret_map[vt3dobj] = obj3d
+
+        # step forward
+        progress.step()
+
+    # leave progress and return
+    progress.leave_substeps()
+    return obj3d_cret_map
+
+def _import_virtools_lights(
+        reader: bmap.BMFileReader, 
+        progress: ProgressReport,
+        resolver: UTIL_ioport_shared.ConflictResolver
+        ) -> None:
+    # prepare progress
+    tr_text: str = bpy.app.translations.pgettext_rpt('Loading Lights', 'BBP_OT_import_virtools/execute')
+    progress.enter_substeps(reader.get_target_light_count(), tr_text)
+
+    # please note light is slightly different between virtools and blender.
+    # in virtools, light is the sub class of 3d entity.
+    # it means that virtools use class inheritance to implement light.
+    # however, in blender, light is the data property of object.
+    # comparing with normal mesh object, it just replace the data property of object to a light.
+    # so in blender, light is implemented as a data struct attached to object.
+    # thus we can reuse light data for multiple objects but virtools can not.
+    # in virtools, every light are individual objects.
+    for vtlight in reader.get_target_lights():
+        # create light data block and 3d object together
+        (light_3dobj, light, init_light) = resolver.create_light(
+            UTIL_virtools_types.virtools_name_regulator(vtlight.get_name())
+        )
+
+        if init_light:
+            # setup light data block
+            rawlight: PROP_virtools_light.RawVirtoolsLight = PROP_virtools_light.RawVirtoolsLight()
+            rawlight.mType = vtlight.get_type()
+            rawlight.mColor = vtlight.get_color()
+
+            rawlight.mConstantAttenuation = vtlight.get_constant_attenuation()
+            rawlight.mLinearAttenuation = vtlight.get_linear_attenuation()
+            rawlight.mQuadraticAttenuation = vtlight.get_quadratic_attenuation()
+
+            rawlight.mRange = vtlight.get_range()
+
+            rawlight.mHotSpot = vtlight.get_hot_spot()
+            rawlight.mFalloff = vtlight.get_falloff()
+            rawlight.mFalloffShape = vtlight.get_falloff_shape()
+
+            PROP_virtools_light.set_raw_virtools_light(light, rawlight)
+            PROP_virtools_light.apply_to_blender_light(light)
+
+            # setup light associated 3d object
+            # add into scene
+            UTIL_functions.add_into_scene(light_3dobj)
+            # set world matrix
+            vtmat: UTIL_virtools_types.VxMatrix = vtlight.get_world_matrix()
+            UTIL_virtools_types.vxmatrix_conv_co(vtmat)
+            bldmat: mathutils.Matrix = UTIL_virtools_types.vxmatrix_to_blender(vtmat)
+            light_3dobj.matrix_world = UTIL_virtools_types.bldmatrix_patch_light_obj(bldmat)
+            # set visibility
+            light_3dobj.hide_set(not vtlight.get_visibility())
+
+    # leave progress
+    progress.leave_substeps()
+
+def _import_virtools_groups(
+        reader: bmap.BMFileReader, 
+        progress: ProgressReport, 
+        obj3d_cret_map: dict[bmap.BM3dObject, bpy.types.Object]
+        ) -> None:
+    # we need iterate all groups to construct a reversed map
+    # to indicate which groups should this 3dobject be grouped into.
+    reverse_map: dict[bmap.BM3dObject, set[str]] = {}
+    # sector counter to record the maximum sector we have processed.
+    sector_count: int = 1
+
+    # prepare progress
+    tr_text: str = bpy.app.translations.pgettext_rpt('Loading Groups', 'BBP_OT_import_virtools/execute')
+    progress.enter_substeps(reader.get_group_count(), tr_text)
+
+    for vtgroup in reader.get_groups():
+        # if this group do not have name, skip it
+        group_name: str | None = vtgroup.get_name()
+        if group_name is None: continue
+
+        # try extracting sector info
+        potential_sector_count: int | None = UTIL_naming_convension.extract_sector_from_name(group_name)
+        if potential_sector_count is not None:
+            sector_count = max(sector_count, potential_sector_count)
+
+        # creating map
+        for item in vtgroup.get_objects():
+            # get or create set
+            objgroups: set[str] | None = reverse_map.get(item, None)
+            if objgroups is None:
+                objgroups = set()
+                reverse_map[item] = objgroups
+
+            # add into list
+            objgroups.add(group_name)
+            
+        # step
+        progress.step()
+
+    # assign to ballance map info according to gotten sector count
+    map_info: PROP_ballance_map_info.RawBallanceMapInfo = PROP_ballance_map_info.get_raw_ballance_map_info(bpy.context.scene)
+    map_info.mSectorCount = max(map_info.mSectorCount, sector_count)
+    PROP_ballance_map_info.set_raw_ballance_map_info(bpy.context.scene, map_info)
+
+    # leave progress
+    progress.leave_substeps()
+
+    # now we can assign 3dobject group data by reverse map
+    tr_text: str = bpy.app.translations.pgettext_rpt('Applying Groups', 'BBP_OT_import_virtools/execute')
+    progress.enter_substeps(len(reverse_map), tr_text)
+    for mapk, mapv in reverse_map.items():
+        # check object
+        assoc_obj = obj3d_cret_map.get(mapk, None)
+        if assoc_obj is None: continue
+
+        # assign group
+        with PROP_virtools_group.VirtoolsGroupsHelper(assoc_obj) as gpoper:
+            gpoper.clear_groups()
+            gpoper.add_groups(mapv)
+
+        # step
+        progress.step()
+
+    # leave progress
+    progress.leave_substeps()
+
+
+def register() -> None:
+    bpy.utils.register_class(BBP_OT_import_virtools)
+
+def unregister() -> None:
+    bpy.utils.unregister_class(BBP_OT_import_virtools)

bbp_ng/OP_MTL_fix_material.py

@@ -0,0 +1,42 @@
+import bpy
+from . import UTIL_functions
+from . import PROP_virtools_material, PROP_preferences
+
+class BBP_OT_fix_all_material(bpy.types.Operator):
+    """Fix All Materials by Its Referred Ballance Texture Name."""
+    bl_idname = "bbp.fix_all_material"
+    bl_label = "Fix All Materials"
+    bl_options = {'UNDO'}
+    bl_translation_context = 'BBP_OT_fix_all_material'
+    
+    @classmethod
+    def poll(cls, context):
+        # only enable this when plugin have a valid ballance texture folder
+        # and we are in object mode
+        return PROP_preferences.get_raw_preferences().has_valid_blc_tex_folder() and UTIL_functions.is_in_object_mode()
+    
+    def invoke(self, context, event):
+        wm = context.window_manager
+        return wm.invoke_confirm(self, event)
+    
+    def execute(self, context):
+        # do work and count 
+        counter_all: int = 0
+        counter_suc: int = 0
+        for mtl in bpy.data.materials:
+            counter_all += 1
+            if PROP_virtools_material.fix_material(mtl):
+                PROP_virtools_material.apply_to_blender_material(mtl)
+                counter_suc += 1
+
+        # report and return
+        tr_text: str = bpy.app.translations.pgettext_rpt(
+            'Fix {0}/{1} materials.', 'BBP_OT_fix_all_material/draw')
+        self.report({'INFO'}, tr_text.format(counter_suc, counter_all))
+        return {'FINISHED'}
+
+def register() -> None:
+    bpy.utils.register_class(BBP_OT_fix_all_material)
+
+def unregister() -> None:
+    bpy.utils.unregister_class(BBP_OT_fix_all_material)

bbp_ng/OP_OBJECT_legacy_align.py

@@ -0,0 +1,298 @@
+import bpy, mathutils
+import enum, typing
+from . import UTIL_functions
+
+#region Align Mode 
+
+class AlignMode(enum.IntEnum):
+    Min = enum.auto()
+    BBoxCenter = enum.auto()
+    AxisCenter = enum.auto()
+    Max = enum.auto()
+_g_AlignModeDesc: dict[AlignMode, tuple[str, str]] = {
+    AlignMode.Min: ("Min", "The min value in specified axis."),
+    AlignMode.BBoxCenter: ("Center (Bounding Box)", "The bounding box center in specified axis."),
+    AlignMode.AxisCenter: ("Center (Axis)", "The object's source point in specified axis."),
+    AlignMode.Max: ("Max", "The max value in specified axis."),
+}
+_g_EnumHelper_AlignMode: UTIL_functions.EnumPropHelper = UTIL_functions.EnumPropHelper(
+    AlignMode,
+    lambda x: str(x.value),
+    lambda x: AlignMode(int(x)),
+    lambda x: _g_AlignModeDesc[x][0],
+    lambda x: _g_AlignModeDesc[x][1],
+    lambda _: ''
+)
+
+#endregion
+
+#region Align Cache Implement
+
+## As we known, 3ds Max's align window have a Apply button which can apply current align to scene, 
+#  and user call set next align settings after clicking Apply. It will not affect previous set align settings.
+#  But Blender have no vanilla Apply function for operator. The only possible way is re-run this operator.
+#  However the experience is pretty shit. Because the window still locate at the left-bottom corner.
+#  User can't keep up to change it.
+#  
+#  We use a dirty way to implement Apply function. The solution is pretty like BME struct adder.
+#  We use a CollectionProperty to store all align steps.
+#  And use a BoolProperty with update function to implement Apply button. Once its value changed,
+#  reset its value (order a recursive hinder), and add a new settings.
+
+class BBP_PG_legacy_align_history(bpy.types.PropertyGroup):
+    align_x: bpy.props.BoolProperty(
+        name = "X Position",
+        default = False,
+        translation_context = 'BBP_PG_legacy_align_history/property'
+    ) # type: ignore
+    align_y: bpy.props.BoolProperty(
+        name = "Y Position",
+        default = False,
+        translation_context = 'BBP_PG_legacy_align_history/property'
+    ) # type: ignore
+    align_z: bpy.props.BoolProperty(
+        name = "Z Position",
+        default = False,
+        translation_context = 'BBP_PG_legacy_align_history/property'
+    ) # type: ignore
+    current_align_mode: bpy.props.EnumProperty(
+        name = "Current Object (Active Object)",
+        items = _g_EnumHelper_AlignMode.generate_items(),
+        default = _g_EnumHelper_AlignMode.to_selection(AlignMode.AxisCenter),
+        translation_context = 'BBP_PG_legacy_align_history/property'
+    ) # type: ignore
+    target_align_mode: bpy.props.EnumProperty(
+        name = "Target Objects (Selected Objects)",
+        items = _g_EnumHelper_AlignMode.generate_items(),
+        default = _g_EnumHelper_AlignMode.to_selection(AlignMode.AxisCenter),
+        translation_context = 'BBP_PG_legacy_align_history/property'
+    ) # type: ignore
+
+#endregion
+
+class BBP_OT_legacy_align(bpy.types.Operator):
+    """Align Objects with 3ds Max Style"""
+    bl_idname = "bbp.legacy_align"
+    bl_label = "3ds Max Align"
+    bl_options = {'REGISTER', 'UNDO'}
+    bl_translation_context = 'BBP_OT_legacy_align'
+
+    # the updator for apply flag value
+    def apply_flag_updated(self, context):
+        # check hinder and set hinder first
+        if self.recursive_hinder: return
+        self.recursive_hinder = True
+
+        # reset apply button value (default is True)
+        # due to the hinder, no recursive calling will happend
+        if self.apply_flag == True: return
+        self.apply_flag = True
+
+        # check whether add new entry
+        # if no selected axis, this alignment is invalid
+        histories: UTIL_functions.CollectionVisitor[BBP_PG_legacy_align_history]
+        histories = UTIL_functions.CollectionVisitor(self.align_history)
+        entry: BBP_PG_legacy_align_history = histories[-1]
+        if entry.align_x == True or entry.align_y == True or entry.align_z == True:
+            # valid one
+            # add a new entry in history
+            histories.add()
+        else:
+            # invalid one
+            # reset all data to default
+            entry.align_x = False
+            entry.align_y = False
+            entry.align_z = False
+            entry.current_align_mode = _g_EnumHelper_AlignMode.to_selection(AlignMode.AxisCenter)
+            entry.target_align_mode = _g_EnumHelper_AlignMode.to_selection(AlignMode.AxisCenter)
+
+        # reset hinder
+        self.recursive_hinder = False
+        # blender required
+        return None
+    
+    apply_flag: bpy.props.BoolProperty(
+        # TR: Property not showen should not have name and desc.
+        # name = "Apply Flag",
+        # description = "Internal flag.",
+        options = {'HIDDEN', 'SKIP_SAVE'},
+        default = True, # default True value to make it as a "light" button, not a grey one.
+        update = apply_flag_updated
+    ) # type: ignore
+    recursive_hinder: bpy.props.BoolProperty(
+        # TR: Property not showen should not have name and desc.
+        # name = "Recursive Hinder",
+        # description = "An internal flag to prevent the loop calling to apply_flags's updator.",
+        options = {'HIDDEN', 'SKIP_SAVE'},
+        default = False
+    ) # type: ignore
+    align_history : bpy.props.CollectionProperty(
+        # TR: Property not showen should not have name and desc.
+        # name = "Historys",
+        # description = "Align history.",
+        type = BBP_PG_legacy_align_history
+    ) # type: ignore
+    
+    @classmethod
+    def poll(cls, context):
+        return _check_align_requirement()
+
+    def invoke(self, context, event):
+        histories: UTIL_functions.CollectionVisitor[BBP_PG_legacy_align_history]
+        histories = UTIL_functions.CollectionVisitor(self.align_history)
+        # clear history and add 1 entry for following functions
+        histories.clear()
+        histories.add()
+        # run execute() function
+        return self.execute(context)
+    
+    def execute(self, context):
+        # get processed objects
+        (current_obj, target_objs) = _prepare_objects()
+        # YYC MARK:
+        # This statement is VERY IMPORTANT.
+        # If this statement is not presented, Blender will return identity matrix
+        # when getting world matrix from Object since the second execution of this function.
+        # It seems that Blender fail to read restored value from a new execution.
+        # Additionally, this statement only can be placed in there.
+        # If you place it at the end of this function, it doesn't work.
+        context.view_layer.update()
+        # iterate history to align objects
+        histories: UTIL_functions.CollectionVisitor[BBP_PG_legacy_align_history]
+        histories = UTIL_functions.CollectionVisitor(self.align_history)
+        for entry in histories:
+            _align_objects(
+                current_obj, target_objs,
+                entry.align_x, entry.align_y, entry.align_z,
+                _g_EnumHelper_AlignMode.get_selection(entry.current_align_mode), 
+                _g_EnumHelper_AlignMode.get_selection(entry.target_align_mode)
+            )
+        return {'FINISHED'}
+
+    def draw(self, context):
+        # get last entry in history to show
+        histories: UTIL_functions.CollectionVisitor[BBP_PG_legacy_align_history]
+        histories = UTIL_functions.CollectionVisitor(self.align_history)
+        entry: BBP_PG_legacy_align_history = histories[-1]
+
+        layout = self.layout
+        col = layout.column()
+
+        # show axis
+        col.label(text="Align Axis (Multi-selection)", text_ctxt='BBP_OT_legacy_align/draw')
+        row = col.row()
+        row.prop(entry, "align_x", toggle = 1)
+        row.prop(entry, "align_y", toggle = 1)
+        row.prop(entry, "align_z", toggle = 1)
+
+        # show mode
+        col.separator()
+        col.label(text='Current Object (Active Object)', text_ctxt='BBP_OT_legacy_align/draw')
+        col.prop(entry, "current_align_mode", expand = True)
+        col.label(text='Target Objects (Selected Objects)', text_ctxt='BBP_OT_legacy_align/draw')
+        col.prop(entry, "target_align_mode", expand = True)
+
+        # show apply button
+        col.separator()
+        conditional_disable_area = col.column()
+        # only allow Apply when there is a selected axis
+        conditional_disable_area.enabled = entry.align_x == True or entry.align_y == True or entry.align_z == True
+        # show apply and counter
+        conditional_disable_area.prop(self, 'apply_flag', toggle = 1, text='Apply', icon='CHECKMARK', text_ctxt='BBP_OT_legacy_align/draw')
+        tr_text: str = bpy.app.translations.pgettext_iface(
+            'Total {0} applied alignments', 'BBP_OT_legacy_align/draw')
+        conditional_disable_area.label(text=tr_text.format(len(histories) - 1), translate=False)
+
+#region Core Functions
+
+def _check_align_requirement() -> bool:
+    # if we are not in object mode, do not do legacy align
+    if not UTIL_functions.is_in_object_mode():
+        return False
+    
+    # check current obj
+    if bpy.context.active_object is None:
+        return False
+    # check target obj with filter of current obj
+    length = len(bpy.context.selected_objects)
+    if bpy.context.active_object in bpy.context.selected_objects:
+        length -= 1
+    return length != 0
+
+def _prepare_objects() -> tuple[bpy.types.Object, set[bpy.types.Object]]:
+    # get current object
+    current_obj: bpy.types.Object = bpy.context.active_object
+
+    # get target objects
+    target_objs: set[bpy.types.Object] = set(bpy.context.selected_objects)
+    # remove active one
+    if current_obj in target_objs:
+        target_objs.remove(current_obj)
+
+    # return value
+    return (current_obj, target_objs)
+
+def _align_objects(
+        current_obj: bpy.types.Object, target_objs: set[bpy.types.Object],
+        align_x: bool, align_y: bool, align_z: bool, current_mode: AlignMode, target_mode: AlignMode) -> None:
+    # if no align, skip
+    if not (align_x or align_y or align_z):
+        return
+    
+    # calc current object data
+    current_obj_ref: mathutils.Vector = _get_object_ref_point(current_obj, current_mode)
+
+    # process each target obj
+    for target_obj in target_objs:
+        # calc target object data
+        target_obj_ref: mathutils.Vector = _get_object_ref_point(target_obj, target_mode)
+        # build translation transform
+        target_obj_translation: mathutils.Vector = current_obj_ref - target_obj_ref
+        if not align_x: target_obj_translation.x = 0
+        if not align_y: target_obj_translation.y = 0
+        if not align_z: target_obj_translation.z = 0
+        # target_obj.location += target_obj_translation
+        target_obj_translation_matrix: mathutils.Matrix = mathutils.Matrix.Translation(target_obj_translation)
+        # apply translation transform to left side (add into original matrix)
+        target_obj.matrix_world = target_obj_translation_matrix @ target_obj.matrix_world
+
+    bpy.context.scene.update_tag
+
+def _get_object_ref_point(obj: bpy.types.Object, mode: AlignMode) -> mathutils.Vector:
+    ref_pos: mathutils.Vector = mathutils.Vector((0, 0, 0))
+    
+    # calc bounding box data
+    corners: tuple[mathutils.Vector] = tuple(obj.matrix_world @ mathutils.Vector(corner) for corner in obj.bound_box)
+    bbox_min_corner: mathutils.Vector = mathutils.Vector((0, 0, 0))
+    bbox_min_corner.x = min((vec.x for vec in corners))
+    bbox_min_corner.y = min((vec.y for vec in corners))
+    bbox_min_corner.z = min((vec.z for vec in corners))
+    bbox_max_corner: mathutils.Vector = mathutils.Vector((0, 0, 0))
+    bbox_max_corner.x = max((vec.x for vec in corners))
+    bbox_max_corner.y = max((vec.y for vec in corners))
+    bbox_max_corner.z = max((vec.z for vec in corners))
+
+    # return value by given align mode
+    match(mode):
+        case AlignMode.Min:
+            ref_pos = bbox_min_corner
+        case AlignMode.Max:
+            ref_pos = bbox_max_corner
+        case AlignMode.BBoxCenter:
+            ref_pos = (bbox_max_corner + bbox_min_corner) / 2
+        case AlignMode.AxisCenter:
+            ref_pos = obj.matrix_world.translation
+        case _:
+            raise UTIL_functions.BBPException('impossible align mode.')
+
+    return ref_pos
+
+#endregion
+
+def register() -> None:
+    bpy.utils.register_class(BBP_PG_legacy_align_history)
+    bpy.utils.register_class(BBP_OT_legacy_align)
+
+def unregister() -> None:
+    bpy.utils.unregister_class(BBP_OT_legacy_align)
+    bpy.utils.unregister_class(BBP_PG_legacy_align_history)

bbp_ng/OP_OBJECT_naming_convention.py

@@ -0,0 +1,107 @@
+import bpy
+import typing
+from . import UTIL_naming_convension, UTIL_functions, UTIL_icons_manager
+
+class BBP_OT_regulate_objects_name(bpy.types.Operator):
+    """Regulate Objects Name by Virtools Group and Naming Convention"""
+    bl_idname = "bbp.regulate_objects_name"
+    bl_label = "Regulate Objects Name"
+    bl_options = {'UNDO'}
+    bl_translation_context = 'BBP_OT_regulate_objects_name'
+
+    def invoke(self, context, event):
+        wm = context.window_manager
+        return wm.invoke_confirm(self, event)
+
+    def execute(self, context):
+        _rename_core(
+            UTIL_naming_convension.VirtoolsGroupConvention.parse_from_object,
+            UTIL_naming_convension.YYCToolchainConvention.set_to_object
+        )
+        return {'FINISHED'}
+
+class BBP_OT_auto_grouping(bpy.types.Operator):
+    """Auto Grouping Objects by Its Name and Name Convention"""
+    bl_idname = "bbp.auto_grouping"
+    bl_label = "Auto Grouping"
+    bl_options = {'UNDO'}
+    bl_translation_context = 'BBP_OT_auto_grouping'
+
+    def invoke(self, context, event):
+        wm = context.window_manager
+        return wm.invoke_confirm(self, event)
+
+    def execute(self, context):
+        _rename_core(
+            UTIL_naming_convension.YYCToolchainConvention.parse_from_object,
+            UTIL_naming_convension.VirtoolsGroupConvention.set_to_object
+        )
+        return {'FINISHED'}
+
+class BBP_OT_convert_to_imengyu(bpy.types.Operator):
+    """Convert Objects Name from YYC Convention to Imengyu Convention."""
+    bl_idname = "bbp.convert_to_imengyu"
+    bl_label = "Convert to Imengyu"
+    bl_options = {'UNDO'}
+    bl_translation_context = 'BBP_OT_convert_to_imengyu'
+
+    def invoke(self, context, event):
+        wm = context.window_manager
+        return wm.invoke_confirm(self, event)
+
+    def execute(self, context):
+        _rename_core(
+            UTIL_naming_convension.YYCToolchainConvention.parse_from_object,
+            UTIL_naming_convension.ImengyuConvention.set_to_object
+        )
+        return {'FINISHED'}
+
+def _rename_core(
+    fct_get_info: typing.Callable[[bpy.types.Object, UTIL_naming_convension.RenameErrorReporter], UTIL_naming_convension.BallanceObjectInfo | None],
+    ftc_set_info: typing.Callable[[bpy.types.Object, UTIL_naming_convension.BallanceObjectInfo, UTIL_naming_convension.RenameErrorReporter], bool]
+    ) -> None:
+    # get selected objects. allow nested collection
+    selected_objects: typing.Iterable[bpy.types.Object] = bpy.context.view_layer.active_layer_collection.collection.all_objects
+    
+    # create reporter
+    with UTIL_naming_convension.RenameErrorReporter() as reporter:
+        # iterate objects
+        for obj in selected_objects:
+            reporter.enter_object(obj)
+            
+            # try get info
+            info: UTIL_naming_convension.BallanceObjectInfo | None = fct_get_info(obj, reporter)
+            if info is not None:
+                # if info is valid, try assign it
+                if not ftc_set_info(obj, info, reporter):
+                    reporter.add_error('Fail to set info to object.')
+            else:
+                reporter.add_error('Fail to get info from object.')
+
+            # end obj process
+            reporter.leave_object(obj)
+
+        # report data
+        tr_text_title: str = bpy.app.translations.pgettext_rpt('Rename System Report', 'BBP/OP_OBJECT_naming_convention._rename_core()')
+        tr_text_1: str = bpy.app.translations.pgettext_rpt('View console to get more detail', 'BBP/OP_OBJECT_naming_convention._rename_core()')
+        tr_text_2: str = bpy.app.translations.pgettext_rpt('All: {0}', 'BBP/OP_OBJECT_naming_convention._rename_core()')
+        tr_text_3: str = bpy.app.translations.pgettext_rpt('Failed: {0}', 'BBP/OP_OBJECT_naming_convention._rename_core()')
+        UTIL_functions.message_box(
+            (
+                tr_text_1,
+                tr_text_2.format(reporter.get_all_objs_count()),
+                tr_text_3.format(reporter.get_failed_objs_count())
+            ),
+            tr_text_title,
+            UTIL_icons_manager.BlenderPresetIcons.Info.value
+        )
+
+def register() -> None:
+    bpy.utils.register_class(BBP_OT_regulate_objects_name)
+    bpy.utils.register_class(BBP_OT_auto_grouping)
+    bpy.utils.register_class(BBP_OT_convert_to_imengyu)
+
+def unregister() -> None:
+    bpy.utils.unregister_class(BBP_OT_convert_to_imengyu)
+    bpy.utils.unregister_class(BBP_OT_auto_grouping)
+    bpy.utils.unregister_class(BBP_OT_regulate_objects_name)

bbp_ng/OP_OBJECT_snoop_group_then_to_mesh.py

@@ -0,0 +1,46 @@
+import bpy
+import typing
+from . import PROP_virtools_group
+
+class BBP_OT_snoop_group_then_to_mesh(bpy.types.Operator):
+    """Convert selected objects into mesh objects and try to copy the Virtools Group infos of their associated curve bevel object if they have. """
+    bl_idname = "bbp.snoop_group_then_to_mesh"
+    bl_label = "Snoop Group then to Mesh"
+    bl_options = {'UNDO'}
+    bl_translation_context = 'BBP_OT_snoop_group_then_to_mesh'
+
+    @classmethod
+    def poll(cls, context):
+        return len(context.selected_objects) != 0
+
+    def execute(self, context):
+        for obj in context.selected_objects:
+            # skip all non-curve object
+            if obj.type != 'CURVE': continue
+            
+            # fetch curve data block
+            curve: bpy.types.Curve = typing.cast(bpy.types.Curve, obj.data)
+
+            # if bevel mode is not object, skip
+            if curve.bevel_mode != 'OBJECT': continue
+            # if bevel object is None, skip
+            bevel_obj: bpy.types.Object | None = curve.bevel_object
+            if bevel_obj is None: continue
+
+            # copy bevel object group info into current object
+            with PROP_virtools_group.VirtoolsGroupsHelper(obj) as this_gp:
+                this_gp.clear_groups()
+                with PROP_virtools_group.VirtoolsGroupsHelper(bevel_obj) as bevel_gp:
+                    this_gp.add_groups(bevel_gp.iterate_groups())
+
+        # convert all selected object to mesh 
+        # no matter the success of copying virtools group infos and whether selected object is curve
+        bpy.ops.object.convert(target = 'MESH')
+        
+        return {'FINISHED'}
+
+def register() -> None:
+    bpy.utils.register_class(BBP_OT_snoop_group_then_to_mesh)
+
+def unregister() -> None:
+    bpy.utils.unregister_class(BBP_OT_snoop_group_then_to_mesh)

bbp_ng/OP_OBJECT_virtools_group.py

@@ -0,0 +1,212 @@
+import bpy
+import enum
+from . import PROP_virtools_group
+from . import UTIL_functions
+
+#region Select by Group
+
+class SelectMode(enum.IntEnum):
+    Set = enum.auto()
+    Extend = enum.auto()
+    Subtract = enum.auto()
+    Difference = enum.auto()
+    Intersect = enum.auto()
+_g_SelectModeDesc: dict[SelectMode, tuple[str, str, str]] = {
+    SelectMode.Set: ('Set', 'Sets a new selection.', 'SELECT_SET'),
+    SelectMode.Extend: ('Extend', 'Adds newly selected items to the existing selection.', 'SELECT_EXTEND'),
+    SelectMode.Subtract: ('Subtract', 'Removes newly selected items from the existing selection.', 'SELECT_SUBTRACT'),
+    SelectMode.Difference: ('Invert', 'Inverts the selection.', 'SELECT_DIFFERENCE'),
+    SelectMode.Intersect: ('Intersect', 'Selects items that intersect with the existing selection.', 'SELECT_INTERSECT')
+}
+_g_EnumHelper_SelectMode: UTIL_functions.EnumPropHelper = UTIL_functions.EnumPropHelper(
+    SelectMode,
+    lambda x: str(x.value),
+    lambda x: SelectMode(int(x)),
+    lambda x: _g_SelectModeDesc[x][0],
+    lambda x: _g_SelectModeDesc[x][1],
+    lambda x: _g_SelectModeDesc[x][2]
+)
+
+class BBP_OT_select_object_by_virtools_group(bpy.types.Operator, PROP_virtools_group.SharedGroupNameInputProperties):
+    """Select Objects by Virtools Group"""
+    bl_idname = "bbp.select_object_by_virtools_group"
+    bl_label = "Select by Virtools Group"
+    bl_options = {'UNDO'}
+    bl_translation_context = 'BBP_OT_select_object_by_virtools_group'
+
+    selection_mode: bpy.props.EnumProperty(
+        name = "Mode",
+        description = "Selection mode",
+        items = _g_EnumHelper_SelectMode.generate_items(),
+        default = _g_EnumHelper_SelectMode.to_selection(SelectMode.Intersect),
+        translation_context = 'BBP_OT_select_object_by_virtools_group/property'
+    ) # type: ignore
+
+    @classmethod
+    def poll(cls, context):
+        return UTIL_functions.is_in_object_mode()
+
+    def invoke(self, context, event):
+        wm = context.window_manager
+        return wm.invoke_props_dialog(self)
+
+    def execute(self, context):
+        _select_object_by_virtools_group(
+            context,
+            self.general_get_group_name(),
+            _g_EnumHelper_SelectMode.get_selection(self.selection_mode)
+        )
+        return {'FINISHED'}
+
+    def draw(self, context):
+        layout = self.layout
+        layout.label(text='Selection Mode', text_ctxt='BBP_OT_select_object_by_virtools_group/draw')
+        sublayout = layout.column()    # make selection expand vertically, not horizontal.
+        sublayout.prop(self, 'selection_mode', expand = True)
+
+        layout.separator()
+        layout.label(text='Group Parameters', text_ctxt='BBP_OT_select_object_by_virtools_group/draw')
+        self.draw_group_name_input(layout)
+
+def _select_object_by_virtools_group(context: bpy.types.Context, group_name: str, mode: SelectMode) -> None:
+    match(mode):
+        case SelectMode.Set:
+            # iterate all objects and directly set
+            for obj in context.scene.objects:
+                # check group and decide whether select this obj
+                with PROP_virtools_group.VirtoolsGroupsHelper(obj) as gp:
+                    obj.select_set(gp.contain_group(group_name))
+        case SelectMode.Extend:
+            # also iterate all objects
+            for obj in context.scene.objects:
+                # but only increase selection, for selected object, skip check
+                if obj.select_get(): continue
+                # if not selected, check whether add it.
+                with PROP_virtools_group.VirtoolsGroupsHelper(obj) as gp:
+                    if gp.contain_group(group_name):
+                        obj.select_set(True)
+        case SelectMode.Subtract:
+            # subtract only involving selected item. so we get selected objest first
+            # and copy it (because we need modify it)
+            # and iterate it to reduce useless operations
+            selected = context.selected_objects[:]
+            for obj in selected:
+                # remove matched only
+                with PROP_virtools_group.VirtoolsGroupsHelper(obj) as gp:
+                    if gp.contain_group(group_name):
+                        obj.select_set(False)
+        case SelectMode.Difference:
+            # construct a selected obj set for convenient operations
+            selected_set = set(context.selected_objects)
+            # iterate all objects
+            for obj in context.scene.objects:
+                with PROP_virtools_group.VirtoolsGroupsHelper(obj) as gp:
+                    # use xor to select
+                    # in_selected XOR in_group
+                    obj.select_set((obj in selected_set) ^ gp.contain_group(group_name))
+        case SelectMode.Intersect:
+            # like subtract, only iterate selected obj
+            selected = context.selected_objects[:]
+            for obj in selected:
+                # but remove not matched
+                with PROP_virtools_group.VirtoolsGroupsHelper(obj) as gp:
+                    if not gp.contain_group(group_name):
+                        obj.select_set(False)
+        case _:
+            raise UTIL_functions.BBPException('invalid selection mode')
+        
+#endregion
+
+#region Objects Group Opers
+
+class BBP_OT_add_objects_virtools_group(bpy.types.Operator, PROP_virtools_group.SharedGroupNameInputProperties):
+    """Grouping Selected Objects"""
+    bl_idname = "bbp.add_objects_virtools_group"
+    bl_label = "Grouping Objects"
+    bl_options = {'UNDO'}
+    bl_translation_context = 'BBP_OT_add_objects_virtools_group'
+
+    @classmethod
+    def poll(cls, context):
+        return len(context.selected_objects) != 0
+
+    def invoke(self, context, event):
+        wm = context.window_manager
+        return wm.invoke_props_dialog(self)
+
+    def execute(self, context):
+        group_name: str = self.general_get_group_name()
+        for obj in context.selected_objects:
+            with PROP_virtools_group.VirtoolsGroupsHelper(obj) as gp:
+                gp.add_group(group_name)
+        self.report({'INFO'}, "Grouping objects successfully.")
+        return {'FINISHED'}
+
+    def draw(self, context):
+        self.draw_group_name_input(self.layout)
+
+class BBP_OT_rm_objects_virtools_group(bpy.types.Operator, PROP_virtools_group.SharedGroupNameInputProperties):
+    """Ungrouping Selected Objects"""
+    bl_idname = "bbp.rm_objects_virtools_group"
+    bl_label = "Ungrouping Objects"
+    bl_options = {'UNDO'}
+    bl_translation_context = 'BBP_OT_rm_objects_virtools_group'
+
+    @classmethod
+    def poll(cls, context):
+        return len(context.selected_objects) != 0
+
+    def invoke(self, context, event):
+        wm = context.window_manager
+        return wm.invoke_props_dialog(self)
+
+    def execute(self, context):
+        group_name: str = self.general_get_group_name()
+        for obj in context.selected_objects:
+            with PROP_virtools_group.VirtoolsGroupsHelper(obj) as gp:
+                gp.remove_group(group_name)
+        self.report({'INFO'}, "Ungrouping objects successfully.")
+        return {'FINISHED'}
+
+    def draw(self, context):
+        self.draw_group_name_input(self.layout)
+
+class BBP_OT_clear_objects_virtools_group(bpy.types.Operator):
+    """Clear Virtools Groups on Selected Objects"""
+    bl_idname = "bbp.clear_objects_virtools_group"
+    bl_label = "Clear All Groups"
+    bl_options = {'UNDO'}
+    bl_translation_context = 'BBP_OT_clear_objects_virtools_group'
+
+    @classmethod
+    def poll(cls, context):
+        return len(context.selected_objects) != 0
+
+    def invoke(self, context, event):
+        wm = context.window_manager
+        return wm.invoke_confirm(self, event)
+
+    def execute(self, context):
+        # iterate object
+        for obj in context.selected_objects:
+            with PROP_virtools_group.VirtoolsGroupsHelper(obj) as gp:
+                gp.clear_groups()
+        self.report({'INFO'}, "Clear objects groups successfully.")
+        return {'FINISHED'}
+
+#endregion
+
+def register() -> None:
+    bpy.utils.register_class(BBP_OT_select_object_by_virtools_group)
+
+    bpy.utils.register_class(BBP_OT_add_objects_virtools_group)
+    bpy.utils.register_class(BBP_OT_rm_objects_virtools_group)
+    bpy.utils.register_class(BBP_OT_clear_objects_virtools_group)
+
+def unregister() -> None:
+    bpy.utils.unregister_class(BBP_OT_clear_objects_virtools_group)
+    bpy.utils.unregister_class(BBP_OT_rm_objects_virtools_group)
+    bpy.utils.unregister_class(BBP_OT_add_objects_virtools_group)
+
+    bpy.utils.unregister_class(BBP_OT_select_object_by_virtools_group)
+

bbp_ng/OP_UV_flatten_uv.py

@@ -0,0 +1,584 @@
+import bpy, mathutils, bmesh
+import typing, enum, collections
+from . import UTIL_virtools_types, UTIL_functions
+
+#region Param Struct
+
+class FlattenMethod(enum.IntEnum):
+    # The legacy flatten uv mode. Only just do space convertion for each individual faces.
+    Raw = enum.auto()
+    # The floor specific flatten uv.
+    # This method will make sure the continuity in V axis in uv when flatten uv.
+    # Only support rectangle faces.
+    Floor = enum.auto()
+    # The wood specific flatten uv.
+    # Similar floor, but it will force all horizontal uv edge parallel with U axis.
+    # Not only V axis, but also U axis' continuity will been make sure.
+    Wood = enum.auto()
+
+class NeighborType(enum.IntEnum):
+    """
+    NeighborType is used by special flatten uv to describe the direction of neighbor.
+
+    Normally we find neighbor by +V, +U direction (in UV world), these neighbors are "forward" neighbors and marked as Forward.
+    But if we try finding neighbor by -V, -U direction, we call these neighbors are "backward" neighbors,
+    and marked as VerticalBackward or HorizontalBackward by its direction.
+
+    The UV of Backward neighbor need to be processed specially so we need distinguish them with Forward neighbors.
+    """
+    # +V, +U direction neighbor.
+    Forward = enum.auto()
+    # -V direction neighbor.
+    VerticalBackward = enum.auto()
+    # -U direction neighbor.
+    HorizontalBackward = enum.auto()
+
+class FlattenParam():
+    mReferenceEdge: int
+    mUseRefPoint: bool
+    mFlattenMethod: FlattenMethod
+
+    mScaleSize: float
+
+    mReferencePoint: int
+    mReferenceUV: float
+
+    def __init__(self, use_ref_point: bool, reference_edge: int, flatten_method: FlattenMethod) -> None:
+        self.mReferenceEdge = reference_edge
+        self.mUseRefPoint = use_ref_point
+        self.mFlattenMethod = flatten_method
+
+    def is_valid(self) -> bool:
+        """Check whether flatten params is valid"""
+        if self.mUseRefPoint:
+            # ref point should be great than 1.
+            # because 0 and 1 is located at the same line with reference edge.
+            return self.mReferencePoint > 1
+        else:
+            # zero scale size make no sense.
+            return round(self.mScaleSize, 7) != 0.0
+
+    @classmethod
+    def create_by_scale_size(cls, reference_edge: int, flatten_method: FlattenMethod, scale_num: float):
+        val = cls(False, reference_edge, flatten_method)
+        val.mScaleSize = scale_num
+        return val
+
+    @classmethod
+    def create_by_ref_point(cls, reference_edge: int, flatten_method: FlattenMethod, ref_point: int, ref_point_uv: float):
+        val = cls(True, reference_edge, flatten_method)
+        val.mReferencePoint = ref_point
+        val.mReferenceUV = ref_point_uv
+        return val
+
+#endregion
+
+class BBP_OT_flatten_uv(bpy.types.Operator):
+    """Flatten selected face UV. Only works for convex face"""
+    bl_idname = "bbp.flatten_uv"
+    bl_label = "Flatten UV"
+    bl_options = {'REGISTER', 'UNDO'}
+    bl_translation_context = 'BBP_OT_flatten_uv'
+
+    reference_edge: bpy.props.IntProperty(
+        name = "Reference Edge",
+        description = "The references edge of UV.\nIt will be placed in V axis.",
+        min = 0,
+        soft_min = 0, soft_max = 3,
+        default = 0,
+        translation_context = 'BBP_OT_flatten_uv/property'
+    ) # type: ignore
+
+    flatten_method: bpy.props.EnumProperty(
+        name = "Flatten Method",
+        items = [
+            ('RAW', "Raw", "Legacy flatten UV."),
+            ('FLOOR', "Floor", "Floor specific flatten UV."),
+            ('WOOD', "Wood", "Wood specific flatten UV."),
+        ],
+        default = 'RAW',
+        translation_context = 'BBP_OT_flatten_uv/property'
+    ) # type: ignore
+
+    scale_mode: bpy.props.EnumProperty(
+        name = "Scale Mode",
+        items = [
+            ('NUM', "Scale Size", "Scale UV with specific number."),
+            ('REF', "Ref. Point", "Scale UV with Reference Point feature."),
+        ],
+        default = 'NUM',
+        translation_context = 'BBP_OT_flatten_uv/property'
+    ) # type: ignore
+
+    scale_number: bpy.props.FloatProperty(
+        name = "Scale Size",
+        description = "The size which will be applied for scale.",
+        min = 0,
+        soft_min = 0, soft_max = 5,
+        default = 5.0,
+        step = 10,
+        precision = 1,
+        translation_context = 'BBP_OT_flatten_uv/property'
+    ) # type: ignore
+
+    reference_point: bpy.props.IntProperty(
+        name = "Reference Point",
+        description = "The references point of UV.\nIt's U component will be set to the number specified by Reference Point UV.\nThis point index is related to the start point of reference edge.",
+        min = 2,  # 0 and 1 is invalid. we can not order the reference edge to be set on the outside of uv axis
+        soft_min = 2, soft_max = 3,
+        default = 2,
+        translation_context = 'BBP_OT_flatten_uv/property'
+    ) # type: ignore
+
+    reference_uv: bpy.props.FloatProperty(
+        name = "Reference Point UV",
+        description = "The U component which should be applied to references point in UV.",
+        soft_min = 0, soft_max = 1,
+        default = 0.5,
+        step = 10,
+        precision = 2,
+        translation_context = 'BBP_OT_flatten_uv/property'
+    ) # type: ignore
+
+    @classmethod
+    def poll(cls, context):
+        obj = context.active_object
+        if obj is None:
+            return False
+        if obj.type != 'MESH':
+            return False
+        if obj.mode != 'EDIT':
+            return False
+        return True
+
+    def execute(self, context):
+        # construct scale data
+        flatten_method_: FlattenMethod
+        match(self.flatten_method):
+            case 'RAW': flatten_method_ = FlattenMethod.Raw
+            case 'FLOOR': flatten_method_ = FlattenMethod.Floor
+            case 'WOOD': flatten_method_ = FlattenMethod.Wood
+            case _: return {'CANCELLED'}
+
+        flatten_param_: FlattenParam
+        if self.scale_mode == 'NUM':
+            flatten_param_ = FlattenParam.create_by_scale_size(self.reference_edge, flatten_method_, self.scale_number)
+        else:
+            flatten_param_ = FlattenParam.create_by_ref_point(self.reference_edge, flatten_method_, self.reference_point, self.reference_uv)
+        if not flatten_param_.is_valid():
+            return {'CANCELLED'}
+
+        # do flatten uv and report
+        failed: int = _flatten_uv_wrapper(context.active_object.data, flatten_param_)
+        if failed != 0:
+            tr_text: str = bpy.app.translations.pgettext_rpt(
+                '[Flatten UV] {0} faces are not be processed correctly because process failed.', 'BBP_OT_flatten_uv/execute')
+            print(tr_text.format(failed))
+        return {'FINISHED'}
+
+    def draw(self, context):
+        layout = self.layout
+        layout.emboss = 'NORMAL'
+        layout.label(text="Flatten Method", text_ctxt='BBP_OT_flatten_uv/draw')
+        sublayout = layout.row()
+        sublayout.prop(self, "flatten_method", expand = True)
+        layout.prop(self, "reference_edge")
+
+        layout.separator()
+        layout.label(text="Scale Mode", text_ctxt='BBP_OT_flatten_uv/draw')
+        sublayout = layout.row()
+        sublayout.prop(self, "scale_mode", expand = True)
+
+        layout.separator()
+        layout.label(text="Scale Configuration", text_ctxt='BBP_OT_flatten_uv/draw')
+        if self.scale_mode == 'NUM':
+            layout.prop(self, "scale_number")
+        else:
+            layout.prop(self, "reference_point")
+            layout.prop(self, "reference_uv")
+
+#region BMesh Visitor Helper
+
+def _set_face_vertex_uv(face: bmesh.types.BMFace, uv_layer: bmesh.types.BMLayerItem, idx: int, uv: UTIL_virtools_types.ConstVxVector2) -> None:
+    """
+    Help function to set UV data for face.
+
+    @param face[in] The face to be set.
+    @param uv_layer[in] The corresponding uv layer. Hint: it was gotten from BMesh.loops.layers.uv.verify()
+    @param idx[in] The index of trying setting vertex.
+    @param uv[in] The set UV data
+    """
+    face.loops[idx][uv_layer].uv = uv
+
+def _get_face_vertex_uv(face: bmesh.types.BMFace, uv_layer: bmesh.types.BMLayerItem, idx: int) -> UTIL_virtools_types.ConstVxVector2:
+    """
+    Help function to get UV data for face.
+
+    @param face[in] The face to be set.
+    @param uv_layer[in] The corresponding uv layer. Hint: it was gotten from BMesh.loops.layers.uv.verify()
+    @param idx[in] The index of trying setting vertex.
+    @return The UV data
+    """
+    v: mathutils.Vector = face.loops[idx][uv_layer].uv
+    return (v[0], v[1])
+
+def _get_face_vertex_pos(face: bmesh.types.BMFace, idx: int) -> UTIL_virtools_types.ConstVxVector3:
+    """
+    Help function to get vertex position from face by provided index.
+    No index overflow checker. Caller must make sure the provided index is not overflow.
+
+    @param face[in] Bmesh face struct.
+    @param idx[in] The index of trying getting vertex.
+    @return The gotten vertex position.
+    """
+    v: mathutils.Vector = face.loops[idx].vert.co
+    return (v[0], v[1], v[2])
+
+def _circular_clamp_index(v: int, vmax: int) -> int:
+    """
+    Circular clamp face vertex index.
+    Used by _real_flatten_uv.
+
+    @param v[in] The index to clamp
+    @param vmax[in] The count of used face vertex. At least 3.
+    @return The circular clamped value ranging from 0 to vmax.
+    """
+    return v % vmax
+
+#endregion
+
+#region Real Worker Functions
+
+def _flatten_uv_wrapper(mesh: bpy.types.Mesh, flatten_param: FlattenParam) -> int:
+    # create bmesh modifier
+    bm: bmesh.types.BMesh = bmesh.from_edit_mesh(mesh)
+    # use verify() to make sure there is a uv layer to write data
+    # verify() will return existing one or create one if no layer existing.
+    uv_layers: bmesh.types.BMLayerCollection = bm.loops.layers.uv
+    uv_layer: bmesh.types.BMLayerItem = uv_layers.verify()
+
+    # invoke core
+    failed: int
+    match(flatten_param.mFlattenMethod):
+        case FlattenMethod.Raw:
+            failed = _raw_flatten_uv(bm, uv_layer, flatten_param)
+        case FlattenMethod.Floor | FlattenMethod.Wood:
+            failed = _specific_flatten_uv(bm, uv_layer, flatten_param)
+
+    # show the updates in the viewport
+    bmesh.update_edit_mesh(mesh)
+    # return process result
+    return failed
+
+def _raw_flatten_uv(bm: bmesh.types.BMesh, uv_layer: bmesh.types.BMLayerItem, flatten_param: FlattenParam) -> int:
+    # failed counter
+    failed: int = 0
+    # raw flatten uv always use zero offset
+    c_ZeroOffset: mathutils.Vector = mathutils.Vector((0, 0))
+
+    # process each face
+    face: bmesh.types.BMFace
+    for face in bm.faces:
+        # check requirement
+        # skip not selected face
+        if not face.select: continue
+        # skip the face that not fufill reference edge requirement
+        edge_count: int = len(face.loops)
+        if flatten_param.mReferenceEdge >= edge_count:
+            failed += 1
+            continue
+        # skip ref point overflow when using ref point mode
+        if flatten_param.mUseRefPoint and (flatten_param.mReferencePoint >= edge_count):
+            failed += 1
+            continue
+
+        # process this face
+        _flatten_face_uv(face, uv_layer, flatten_param, c_ZeroOffset)
+
+    return failed
+
+def _specific_flatten_uv(bm: bmesh.types.BMesh, uv_layer: bmesh.types.BMLayerItem, flatten_param: FlattenParam) -> int:
+    # failed counter
+    failed: int = 0
+
+    # reset selected face's tag to False to indicate these face is not processed
+    face: bmesh.types.BMFace
+    for face in bm.faces:
+        if face.select:
+            face.tag = False
+    
+    # prepare a function to check whether face is valid
+    def face_validator(f: bmesh.types.BMFace) -> bool:
+        # specify using external failed counter
+        nonlocal failed
+        # a valid face must be
+        # selected, not processed, and should be rectangle
+        # we check selection first
+        # then check tag. if tag == True, it mean this face has been processed.
+        if not f.select or f.tag: return False
+        # now this face can be processed, we need check whether it is rectangle
+        if len(f.loops) == 4:
+            # yes it is rectangle
+            return True
+        else:
+            # no, it is not rectangle
+            # we need mark its tag as True to prevent any possible recursive checking
+            # because it definately can not be processed in future.
+            f.tag = True
+            # then we report this face failed
+            failed = failed + 1
+            # return false
+            return False
+    # prepare face getter which will be used when stack is empty
+    face_getter: typing.Iterator[bmesh.types.BMFace] = filter(
+        lambda f: face_validator(f), 
+        typing.cast(typing.Iterable[bmesh.types.BMFace], bm.faces)
+    )
+    # prepare a neighbor getter.
+    # this function will help finding the valid neighbor of specified face
+    # `loop_idx` is the index of loop getting from given face.
+    # `exp_loop_idx` is the expected index of neighbor loop in neighbor face.
+    def face_neighbor_getter(f: bmesh.types.BMFace, loop_idx: int, exp_loop_idx: int) -> bmesh.types.BMFace | None:
+        # get this face's loop
+        this_loop: bmesh.types.BMLoop = f.loops[loop_idx]
+        # check requirement for this loop
+        # this edge should be shared exactly by 2 faces.
+        # 
+        # Manifold: For a mesh to be manifold, every edge must have exactly two adjacent faces.
+        # Ref: https://github.com/rlguy/Blender-FLIP-Fluids/wiki/Manifold-Meshes
+        if not this_loop.edge.is_manifold:
+            return None
+
+        # get neighbor loop
+        neighbor_loop: bmesh.types.BMLoop = this_loop.link_loop_radial_next
+        # get neighbor face and check it
+        neighbor_f: bmesh.types.BMFace = neighbor_loop.face
+        if not face_validator(neighbor_f):
+            return None
+
+        # check expected neighbor index
+        if neighbor_loop != neighbor_f.loops[exp_loop_idx]:
+            return None
+
+        # all check done, return face
+        return neighbor_f
+    # prepare face stack.
+    # NOTE: all face inserted into this stack should be marked as processed first.
+    face_stack: collections.deque[tuple[bmesh.types.BMFace, mathutils.Vector, NeighborType]] = collections.deque()
+    # start process faces
+    while True:
+        # if no item in face stack, pick one from face getter and mark it as processed
+        # if face getter failed, it mean that no more face, exit.
+        if len(face_stack) == 0:
+            try:
+                f = next(face_getter)
+                f.tag = True
+                face_stack.append((f, mathutils.Vector((0, 0)), NeighborType.Forward))
+            except StopIteration:
+                break
+
+        # pick one face from stack and process it
+        (face, face_offset, face_backward) = face_stack.pop()
+        _flatten_face_uv(face, uv_layer, flatten_param, face_offset)
+
+        # get 4 point uv because we need use them later
+        # NOTE: 4 uv point following this order
+        #  +-----------+
+        #  |(1)        |(2)
+        #  |           |
+        #  |(0)        |(3)
+        #  +-----------+
+        # So the loop index is
+        #        (1)
+        #  +---------->+
+        #  ^           |
+        #  |(0)        |(2)
+        #  |           v
+        #  +<----------+
+        #        (3)
+        ind0 = _circular_clamp_index(flatten_param.mReferenceEdge, 4)
+        ind1 = _circular_clamp_index(flatten_param.mReferenceEdge + 1, 4)
+        ind2 = _circular_clamp_index(flatten_param.mReferenceEdge + 2, 4)
+        ind3 = _circular_clamp_index(flatten_param.mReferenceEdge + 3, 4)
+        uv0 = _get_face_vertex_uv(face, uv_layer, ind0)
+        uv1 = _get_face_vertex_uv(face, uv_layer, ind1)
+        uv2 = _get_face_vertex_uv(face, uv_layer, ind2)
+        uv3 = _get_face_vertex_uv(face, uv_layer, ind3)
+
+        # correct rectangle shape when in wood mode
+        if flatten_param.mFlattenMethod == FlattenMethod.Wood:
+            # make its uv geometry to rectangle from a trapezium.
+            # get the average U factor from its right edge.
+            # and make top + bottom uv edge be parallel with U axis by using left edge V factor.
+            average_u = (uv2[0] + uv3[0]) / 2
+            uv2 = (average_u, uv1[1])
+            uv3 = (average_u, uv0[1])
+            _set_face_vertex_uv(face, uv_layer, ind2, uv2)
+            _set_face_vertex_uv(face, uv_layer, ind3, uv3)
+        
+        # do backward correction
+        # in backward mode, we can not know how many space backward one will occupied,
+        # thus we can not pass it by offset because we don't know the offset,
+        # so we only can patch it after computing its real size.
+        if face_backward != NeighborType.Forward:
+            if face_backward == NeighborType.VerticalBackward:
+                # in vertical backward patch,
+                # minus self height for all uv.
+                self_height: float = uv1[1] - uv0[1]
+                uv0 = (uv0[0], uv0[1] - self_height)
+                uv1 = (uv1[0], uv1[1] - self_height)
+                uv2 = (uv2[0], uv2[1] - self_height)
+                uv3 = (uv3[0], uv3[1] - self_height)
+            if face_backward == NeighborType.HorizontalBackward:
+                # in horizontal backward patch, minus self width for all uv.
+                # because we have process rectangle shape issue before this,
+                # so we can pick uv2 or uv3 to get width directly.
+                self_width: float = uv3[0] - uv0[0]
+                uv0 = (uv0[0] - self_width, uv0[1])
+                uv1 = (uv1[0] - self_width, uv1[1])
+                uv2 = (uv2[0] - self_width, uv2[1])
+                uv3 = (uv3[0] - self_width, uv3[1])
+            # set modified uv to geometry
+            _set_face_vertex_uv(face, uv_layer, ind0, uv0)
+            _set_face_vertex_uv(face, uv_layer, ind1, uv1)
+            _set_face_vertex_uv(face, uv_layer, ind2, uv2)
+            _set_face_vertex_uv(face, uv_layer, ind3, uv3)
+            
+        # insert horizontal neighbor only in wood mode.
+        if flatten_param.mFlattenMethod == FlattenMethod.Wood:
+            # insert right neighbor (forward)
+            r_face: bmesh.types.BMFace | None = face_neighbor_getter(face, ind2, ind0)
+            if r_face is not None:
+                # mark it as processed
+                r_face.tag = True
+                # insert face with extra horizontal offset.
+                face_stack.append((r_face, mathutils.Vector((uv3[0], uv3[1])), NeighborType.Forward))
+            # insert left neighbor (backward)
+            # swap the index param of neighbor getter
+            l_face: bmesh.types.BMFace | None = face_neighbor_getter(face, ind0, ind2)
+            if l_face is not None:
+                l_face.tag = True
+                # pass origin pos, and order backward correction
+                face_stack.append((l_face, mathutils.Vector((uv0[0], uv0[1])), NeighborType.HorizontalBackward))
+
+        # insert vertical neighbor
+        # insert top neighbor (forward)
+        t_face: bmesh.types.BMFace | None = face_neighbor_getter(face, ind1, ind3)
+        if t_face is not None:
+            # mark it as processed
+            t_face.tag = True
+            # insert face with extra vertical offset.
+            face_stack.append((t_face, mathutils.Vector((uv1[0], uv1[1])), NeighborType.Forward))
+        # insert bottom neighbor (backward)
+        # swap the index param of neighbor getter
+        b_face: bmesh.types.BMFace | None = face_neighbor_getter(face, ind3, ind1)
+        if b_face is not None:
+            b_face.tag = True
+            # pass origin pos, and order backward correction
+            face_stack.append((b_face, mathutils.Vector((uv0[0], uv0[1])), NeighborType.VerticalBackward))
+
+    return failed
+
+def _flatten_face_uv(face: bmesh.types.BMFace, uv_layer: bmesh.types.BMLayerItem, flatten_param: FlattenParam, offset: mathutils.Vector) -> None:
+    # ========== get correct new corrdinate system ==========
+    # yyc mark:
+    # we use 3 points located in this face to calc
+    # the base of this local uv corredinate system.
+    # however if this 3 points are set in a line,
+    # this method will cause a error, zero vector error.
+    #
+    # if z axis is zero vector, we will try using face normal instead
+    # to try getting correct data.
+    #
+    # zero base is not important. because it will not raise any math exception
+    # just a weird uv. user will notice this problem.
+
+    # get point
+    all_point: int = len(face.loops)
+    pidx_start: int = _circular_clamp_index(flatten_param.mReferenceEdge, all_point)
+    p1: mathutils.Vector = mathutils.Vector(_get_face_vertex_pos(face, pidx_start))
+    p2: mathutils.Vector = mathutils.Vector(_get_face_vertex_pos(face, _circular_clamp_index(flatten_param.mReferenceEdge + 1, all_point)))
+    p3: mathutils.Vector = mathutils.Vector(_get_face_vertex_pos(face, _circular_clamp_index(flatten_param.mReferenceEdge + 2, all_point)))
+
+    # get y axis
+    new_y_axis: mathutils.Vector = p2 - p1
+    new_y_axis.normalize()
+    vec1: mathutils.Vector = p3 - p2
+    vec1.normalize()
+
+    # get z axis
+    new_z_axis: mathutils.Vector = vec1.cross(new_y_axis)
+    new_z_axis.normalize()
+    # if z is a zero vector, use face normal instead
+    # please note we need use inverted face normal.
+    if not any(round(v, 7) for v in new_z_axis):
+        new_z_axis = typing.cast(mathutils.Vector, face.normal).normalized()
+        new_z_axis.negate()
+
+    # get x axis
+    new_x_axis: mathutils.Vector = new_y_axis.cross(new_z_axis)
+    new_x_axis.normalize()
+
+    # construct rebase matrix
+    origin_base: mathutils.Matrix = mathutils.Matrix((
+        (1.0, 0, 0), 
+        (0, 1.0, 0), 
+        (0, 0, 1.0)
+    ))
+    origin_base.invert_safe()
+    new_base: mathutils.Matrix = mathutils.Matrix((
+        (new_x_axis.x, new_y_axis.x,  new_z_axis.x), 
+        (new_x_axis.y, new_y_axis.y, new_z_axis.y),
+        (new_x_axis.z, new_y_axis.z, new_z_axis.z)
+    ))
+    transition_matrix: mathutils.Matrix = typing.cast(mathutils.Matrix, origin_base @ new_base)
+    transition_matrix.invert_safe()
+
+    # ===== rescale correction =====
+    rescale: float = 0.0
+    if flatten_param.mUseRefPoint:
+        # ref point method
+        # get reference point from loop
+        pidx_refp: int = _circular_clamp_index(pidx_start + flatten_param.mReferencePoint, all_point)
+        pref: mathutils.Vector = mathutils.Vector(_get_face_vertex_pos(face, pidx_refp)) - p1
+
+        # calc its U component
+        vec_u: float = abs(typing.cast(mathutils.Vector, transition_matrix @ pref).x)
+        if round(vec_u, 7) == 0.0:
+            rescale = 1.0  # fallback. rescale = 1 will not affect anything
+        else:
+            rescale = flatten_param.mReferenceUV / vec_u
+    else:
+        # scale size method
+        # apply rescale directly
+        rescale = 1.0 / flatten_param.mScaleSize
+
+    # construct matrix
+    # we only rescale U component (X component)
+    # and constant 5.0 scale for V component (Y component)
+    scale_matrix: mathutils.Matrix = mathutils.Matrix((
+        (rescale, 0, 0), 
+        (0, 1.0 / 5.0, 0), 
+        (0, 0, 1.0)
+    ))
+    # order can not be changed. we order do transition first, then scale it.
+    rescale_transition_matrix: mathutils.Matrix = typing.cast(mathutils.Matrix, scale_matrix @ transition_matrix)
+
+    # ========== process each face ==========
+    for idx in range(all_point):
+        # compute uv
+        pp: mathutils.Vector = mathutils.Vector(_get_face_vertex_pos(face, idx)) - p1
+        ppuv: mathutils.Vector = typing.cast(mathutils.Vector, rescale_transition_matrix @ pp)
+        # u and v component has been calculated properly. no extra process needed.
+        # just get abs for the u component
+        ppuv.x = abs(ppuv.x)
+        # add offset and assign to uv
+        _set_face_vertex_uv(face, uv_layer, idx, (ppuv.x + offset.x, ppuv.y + offset.y))
+
+#endregion
+
+def register() -> None:
+    bpy.utils.register_class(BBP_OT_flatten_uv)
+
+def unregister() -> None:
+    bpy.utils.unregister_class(BBP_OT_flatten_uv)

bbp_ng/OP_UV_rail_uv.py

@@ -0,0 +1,190 @@
+import bpy, bmesh, mathutils
+import typing
+from . import PROP_ptrprop_resolver
+from . import UTIL_virtools_types, UTIL_icons_manager, UTIL_functions
+
+class BBP_OT_rail_uv(bpy.types.Operator):
+    """Create UV for Rail as Ballance Showen (TT_ReflectionMapping)"""
+    bl_idname = "bbp.rail_uv"
+    bl_label = "Rail UV"
+    bl_options = {'UNDO'}
+    bl_translation_context = 'BBP_OT_rail_uv'
+
+    @classmethod
+    def poll(cls, context):
+        return _check_rail_target(context)
+
+    def invoke(self, context, event):
+        wm: bpy.types.WindowManager = context.window_manager
+        return wm.invoke_props_dialog(self)
+
+    def execute(self, context):
+        # check material
+        ptrprops = PROP_ptrprop_resolver.PropsVisitor(context.scene)
+        mtl: bpy.types.Material = ptrprops.get_rail_uv_material()
+        if mtl is None:
+            self.report({'ERROR'}, "Specified material is empty.")
+            return {'CANCELLED'}
+        
+        # apply rail uv
+        (has_invalid_objs, meshes) = _get_rail_target(context)
+        _create_rail_uv(meshes, mtl)
+
+        # show warning if there is invalid objects
+        if has_invalid_objs:
+            self.report({'WARNING'}, 'Some objects are invalid for this operation. See Console for more details.')
+
+        return {'FINISHED'}
+
+    def draw(self, context):
+        layout: bpy.types.UILayout = self.layout
+        ptrprops = PROP_ptrprop_resolver.PropsVisitor(context.scene)
+        ptrprops.draw_rail_uv_material(layout)
+
+#region Real Worker Functions
+
+def _check_rail_target(context: bpy.types.Context) -> bool:
+    for obj in context.selected_objects:
+        if obj.type != 'MESH':
+            continue
+        if obj.mode != 'OBJECT':
+            continue
+        if obj.data is None:
+            continue
+        return True
+    return False
+
+def _get_rail_target(context: bpy.types.Context) -> tuple[bool, typing.Iterable[bpy.types.Mesh]]:
+    # collect objects
+    meshes: list[bpy.types.Mesh] = []
+    error_objname: list[str] = []
+    for obj in context.selected_objects:
+        if obj.type != 'MESH':
+            error_objname.append(obj.name)
+            continue
+        if obj.mode != 'OBJECT':
+            error_objname.append(obj.name)
+            continue
+        if obj.data is None:
+            error_objname.append(obj.name)
+            continue
+        
+        meshes.append(typing.cast(bpy.types.Mesh, obj.data))
+    
+    # display warning window if necessary
+    has_invalid_objs = len(error_objname) != 0
+    if has_invalid_objs:
+        # output to console
+        print('')
+        tr_text: str = bpy.app.translations.pgettext_rpt('Rail UV Report', 'BBP_OT_rail_uv/execute')
+        print(f'========== {tr_text} ==========')
+        print(bpy.app.translations.pgettext_rpt(
+            'Following objects are not processed by Rail UV because they do not meet the requirements of Rail UV.',
+            'BBP_OT_rail_uv/execute'
+        ))
+        for objname in error_objname:
+            print(objname)
+        print('')
+
+    # return valid
+    return (has_invalid_objs, meshes)
+
+def _tt_reflection_mapping_compute(
+        point_: UTIL_virtools_types.ConstVxVector3, 
+        nml_: UTIL_virtools_types.ConstVxVector3, 
+        refobj_: UTIL_virtools_types.ConstVxVector3) -> UTIL_virtools_types.ConstVxVector2:
+    # switch blender coord to virtools coord for convenient calc
+    point: mathutils.Vector = mathutils.Vector((point_[0], point_[2], point_[1]))
+    nml: mathutils.Vector = mathutils.Vector((nml_[0], nml_[2], nml_[1])).normalized()
+    refobj: mathutils.Vector = mathutils.Vector((refobj_[0], refobj_[2], refobj_[1]))
+
+    p: mathutils.Vector = (refobj - point).normalized()
+    b: mathutils.Vector = (((2 * (p * nml)) * nml) - p)
+    b.normalize()
+    
+    # convert back to blender coord
+    return ((b.x + 1.0) / 2.0, -(b.z + 1.0) / 2.0)
+
+
+def _set_face_vertex_uv(face: bpy.types.MeshPolygon, uv_layer: bpy.types.MeshUVLoopLayer, idx: int, uv: UTIL_virtools_types.ConstVxVector2) -> None:
+    """
+    Help function to set face vertex uv by index.
+
+    @param face[in] The face to be set.
+    @param uv_layer[in] The uv layer to be set gotten from `Mesh.uv_layers.active`
+    @param idx[in] The index related to face to set uv.
+    @param uv[in] The uv data.
+    """
+    uv_layer.uv[face.loop_start + idx].vector = uv
+
+def _get_face_vertex_pos(face: bpy.types.MeshPolygon, loops: bpy.types.MeshLoops, vecs: bpy.types.MeshVertices, idx: int) -> UTIL_virtools_types.ConstVxVector3:
+    """
+    Help function. Get face referenced vertex position data by index
+
+    @param face[in] The face to be set.
+    @param loops[in] Mesh loops gotten from `Mesh.loops`
+    @param vecs[in] Mesh vertices gotten from `Mesh.vertices`
+    @param idx[in] The index related to face to get position.
+    """
+    v: mathutils.Vector = vecs[loops[face.loop_start + idx].vertex_index].co
+    return (v[0], v[1], v[2])
+
+def _get_face_vertex_nml(face: bpy.types.MeshPolygon, loops: bpy.types.MeshLoops, idx: int) -> UTIL_virtools_types.ConstVxVector3:
+    """
+    Help function to get face vertex normal.
+
+    Similar to _get_face_vertex_pos, just get normal, not position.
+
+    @param face[in] The face to be set.
+    @param loops[in] Mesh loops gotten from `Mesh.loops`
+    @param idx[in] The index related to face to get normal.
+    """
+    v: mathutils.Vector = loops[face.loop_start + idx].normal
+    return (v[0], v[1], v[2])
+
+def _get_face_vertex_count(face: bpy.types.MeshPolygon) -> int:
+    """
+    Help function to get how many vertex used by this face.
+
+    @return The count of used vertex. At least 3.
+    """
+    return face.loop_total
+
+def _create_rail_uv(meshes: typing.Iterable[bpy.types.Mesh], mtl: bpy.types.Material):
+    for mesh in meshes:
+        # clean it material and set rail first
+        mesh.materials.clear()
+        mesh.materials.append(mtl)
+        # and validate face mtl idx ref
+        mesh.validate_material_indices()
+        
+        # get uv and make sure at least one uv
+        if mesh.uv_layers.active is None:
+            mesh.uv_layers.new(do_init = False)
+        uv_layer: bpy.types.MeshUVLoopLayer = mesh.uv_layers.active
+        # get other useful data
+        loops: bpy.types.MeshLoops = mesh.loops
+        vecs: bpy.types.MeshVertices = mesh.vertices
+
+        refobj: UTIL_virtools_types.ConstVxVector3 = (0.0, 0.0, 0.0)
+        for face in mesh.polygons:
+            for idx in range(_get_face_vertex_count(face)):
+                _set_face_vertex_uv(
+                    face,
+                    uv_layer,
+                    idx,
+                    _tt_reflection_mapping_compute(
+                        _get_face_vertex_pos(face, loops, vecs, idx),
+                        _get_face_vertex_nml(face, loops, idx),
+                        refobj
+                    )
+                )
+
+#endregion
+
+def register() -> None:
+    bpy.utils.register_class(BBP_OT_rail_uv)
+
+def unregister() -> None:
+    bpy.utils.unregister_class(BBP_OT_rail_uv)
+

bbp_ng/PROP_ballance_element.py

@@ -0,0 +1,396 @@
+import bpy
+import os, typing, enum, array
+from . import PROP_virtools_mesh
+from . import UTIL_functions, UTIL_file_io, UTIL_blender_mesh, UTIL_virtools_types, UTIL_icons_manager
+
+#region Raw Elements Operations
+
+class BallanceElementType(enum.IntEnum):
+    P_Extra_Life = 0
+    P_Extra_Point = 1
+    P_Trafo_Paper = 2
+    P_Trafo_Stone = 3
+    P_Trafo_Wood = 4
+    P_Ball_Paper = 5
+    P_Ball_Stone = 6
+    P_Ball_Wood = 7
+    P_Box = 8
+    P_Dome = 9
+    P_Modul_01 = 10
+    P_Modul_03 = 11
+    P_Modul_08 = 12
+    P_Modul_17 = 13
+    P_Modul_18 = 14
+    P_Modul_19 = 15
+    P_Modul_25 = 16
+    P_Modul_26 = 17
+    P_Modul_29 = 18
+    P_Modul_30 = 19
+    P_Modul_34 = 20
+    P_Modul_37 = 21
+    P_Modul_41 = 22
+    PC_TwoFlames = 23
+    PE_Balloon = 24
+    PR_Resetpoint = 25
+    PS_FourFlames = 26
+
+_g_ElementCount: int = len(BallanceElementType)
+
+def get_ballance_element_type_from_id(id: int) -> BallanceElementType | None:
+    """
+    Get Ballance element type by its id.
+
+    @param id[in] The id of element
+    @return the type of this Ballance element name distributed by this plugin. or None if providing id is invalid.
+    """
+    try:
+        return BallanceElementType(id)  # https://docs.python.org/zh-cn/3/library/enum.html#enum.EnumType.__call__
+    except ValueError:
+        return None
+
+def get_ballance_element_type_from_name(name: str) -> BallanceElementType | None:
+    """
+    Get Ballance element type by its name.
+
+    @param name[in] The name of element
+    @return the type of this Ballance element name distributed by this plugin. or None if providing name is invalid.
+    """
+    try:
+        return BallanceElementType[name]    # https://docs.python.org/zh-cn/3/library/enum.html#enum.EnumType.__getitem__
+    except KeyError:
+        return None
+
+def get_ballance_element_id(ty: BallanceElementType) -> int:
+    """
+    Get Ballance element id by its type
+
+    @param ty[in] The type of element
+    @return the id of this Ballance element.
+    """
+    return ty.value
+
+def get_ballance_element_name(ty: BallanceElementType) -> str:
+    """
+    Get Ballance element name by its type
+
+    @param ty[in] The type of element
+    @return the name of this Ballance element.
+    """
+    return ty.name
+
+def is_ballance_element(name: str) -> bool:
+    """
+    Check whether providing name is Ballance element.
+
+    Just a wrapper of get_ballance_element_id
+
+    @param name[in] The name of element
+    @return True if providing name is Ballance element name.
+    """
+    return get_ballance_element_type_from_name(name) is not None
+
+#endregion
+
+#region Ballance Elements Define & Visitor
+
+class BBP_PG_ballance_element(bpy.types.PropertyGroup):
+    element_id: bpy.props.IntProperty(
+        name = "Element Id",
+        default = 0,
+        translation_context = 'BBP_PG_ballance_element/property'
+    ) # type: ignore
+    
+    mesh_ptr: bpy.props.PointerProperty(
+        name = "Mesh",
+        type = bpy.types.Mesh,
+        translation_context = 'BBP_PG_ballance_element/property'
+    ) # type: ignore
+
+def get_ballance_elements(scene: bpy.types.Scene) -> UTIL_functions.CollectionVisitor[BBP_PG_ballance_element]:
+    return UTIL_functions.CollectionVisitor(scene.ballance_elements)
+
+#endregion
+
+#region Element Loader
+
+def _save_element(mesh: bpy.types.Mesh, filename: str) -> None:
+    # todo: if we need add element placeholder save operator, 
+    # write this function and call this function in operator.
+    pass
+
+def _load_element(mesh: bpy.types.Mesh, element_type: BallanceElementType) -> None:
+    # resolve mesh path
+    element_name: str = get_ballance_element_name(element_type)
+    element_filename: str = os.path.join(
+        os.path.dirname(__file__),
+        "meshes",
+        element_name + '.bin'
+    )
+
+    # open file and read
+    with open(element_filename, 'rb') as fmesh:
+        # prepare container
+        vpos: array.array = array.array('f')
+        vnml: array.array = array.array('f')
+        face: array.array = array.array('L')
+
+        # read data
+        # position is vector3
+        vpos_count = UTIL_file_io.read_uint32(fmesh)
+        vpos.extend(UTIL_file_io.read_float_array(fmesh, vpos_count * 3))
+        # normal is vector3
+        vnml_count = UTIL_file_io.read_uint32(fmesh)
+        vnml.extend(UTIL_file_io.read_float_array(fmesh, vnml_count * 3))
+        # each face use 6 uint32 to describe, 
+        # they are: pos1, nml1, pos2, nml2, pos3, nml3. 
+        # each item is a 0 based index refering to corresponding list
+        face_count = UTIL_file_io.read_uint32(fmesh)
+        face.extend(UTIL_file_io.read_uint32_array(fmesh, face_count * 6))
+
+        # open mesh writer and write data
+        with UTIL_blender_mesh.MeshWriter(mesh) as writer:
+            # prepare writer essential function
+            mesh_part: UTIL_blender_mesh.MeshWriterIngredient = UTIL_blender_mesh.MeshWriterIngredient()
+            def vpos_iterator() -> typing.Iterator[UTIL_virtools_types.VxVector3]:
+                v: UTIL_virtools_types.VxVector3 = UTIL_virtools_types.VxVector3()
+                for i in range(vpos_count):
+                    idx: int = i * 3
+                    v.x = vpos[idx]
+                    v.y = vpos[idx + 1]
+                    v.z = vpos[idx + 2]
+                    # conv co
+                    UTIL_virtools_types.vxvector3_conv_co(v)
+                    yield v
+            mesh_part.mVertexPosition = vpos_iterator()
+            def vnml_iterator() -> typing.Iterator[UTIL_virtools_types.VxVector3]:
+                v: UTIL_virtools_types.VxVector3 = UTIL_virtools_types.VxVector3()
+                for i in range(vnml_count):
+                    idx: int = i * 3
+                    v.x = vnml[idx]
+                    v.y = vnml[idx + 1]
+                    v.z = vnml[idx + 2]
+                    # conv co
+                    UTIL_virtools_types.vxvector3_conv_co(v)
+                    yield v
+            mesh_part.mVertexNormal = vnml_iterator()
+            def vuv_iterator() -> typing.Iterator[UTIL_virtools_types.VxVector2]:
+                # no uv, no need to conv co
+                v: UTIL_virtools_types.VxVector2 = UTIL_virtools_types.VxVector2()
+                yield v
+            mesh_part.mVertexUV = vuv_iterator()
+            mesh_part.mMaterial = iter(tuple())
+            def face_iterator() -> typing.Iterator[UTIL_blender_mesh.FaceData]:
+                # create face data with 3 placeholder
+                f: UTIL_blender_mesh.FaceData = UTIL_blender_mesh.FaceData(
+                    [UTIL_blender_mesh.FaceVertexData() for i in range(3)]
+                )
+                for i in range(face_count):
+                    idx: int = i * 6
+                    f.mIndices[0].mPosIdx = face[idx]
+                    f.mIndices[0].mNmlIdx = face[idx + 1]
+                    f.mIndices[1].mPosIdx = face[idx + 2]
+                    f.mIndices[1].mNmlIdx = face[idx + 3]
+                    f.mIndices[2].mPosIdx = face[idx + 4]
+                    f.mIndices[2].mNmlIdx = face[idx + 5]
+                    # conv co
+                    f.conv_co()
+                    yield f
+            mesh_part.mFace = face_iterator()
+
+            writer.add_ingredient(mesh_part)
+
+        # end of with writer
+        # write mesh data
+
+        # set other mesh settings
+        # generated mesh always use lit mode.
+        mesh_settings: PROP_virtools_mesh.RawVirtoolsMesh = PROP_virtools_mesh.RawVirtoolsMesh()
+        mesh_settings.mLitMode = UTIL_virtools_types.VXMESH_LITMODE.VX_LITMESH
+        PROP_virtools_mesh.set_raw_virtools_mesh(mesh, mesh_settings)
+
+    # end of with fmesh
+    # close file
+
+
+#endregion
+
+#region Ballance Elements Operation Help Class & Functions
+
+class BallanceElementsHelper():
+    """
+    The helper of Ballance elements processing.
+
+    All element operations, including getting or setting, must be manipulated by this class. 
+    You should NOT operate Ballance Elements property (in Scene) directly.
+
+    This class should only have 1 instance at the same time. This class support `with` syntax to achieve this.
+    This class frequently used in importing stage to create element placeholder.
+    """
+    __mSingletonMutex: typing.ClassVar[UTIL_functions.TinyMutex[bpy.types.Scene]] = UTIL_functions.TinyMutex()
+    __mIsValid: bool
+    __mAssocScene: bpy.types.Scene
+    __mElementMap: dict[BallanceElementType, bpy.types.Mesh]
+
+    def __init__(self, assoc: bpy.types.Scene):
+        self.__mElementMap = {}
+        self.__mAssocScene = assoc
+        self.__mIsValid = False
+
+        # check singleton
+        BallanceElementsHelper.__mSingletonMutex.lock(self.__mAssocScene)
+        # set validation and read ballance elements property
+        self.__mIsValid = True
+        self.__read_from_ballance_element()
+
+    def is_valid(self) -> bool:
+        return self.__mIsValid
+    
+    def __enter__(self):
+        return self
+    
+    def __exit__(self, exc_type, exc_value, traceback):
+        self.dispose()
+    
+    def dispose(self) -> None:
+        if self.is_valid():
+            # write to ballance elements property and reset validation
+            self.__write_to_ballance_elements()
+            self.__mIsValid = False
+            BallanceElementsHelper.__mSingletonMutex.unlock(self.__mAssocScene)
+    
+    def get_element(self, element_type: BallanceElementType) -> bpy.types.Mesh:
+        if not self.is_valid():
+            raise UTIL_functions.BBPException('calling invalid BallanceElementsHelper')
+        
+        # get exist one
+        mesh: bpy.types.Mesh | None = self.__mElementMap.get(element_type, None)
+        if mesh is not None: 
+            return mesh
+
+        # if no existing one, create new one
+        new_mesh_name: str = get_ballance_element_name(element_type)
+        new_mesh: bpy.types.Mesh = bpy.data.meshes.new(new_mesh_name)
+
+        _load_element(new_mesh, element_type)
+        self.__mElementMap[element_type] = new_mesh
+        return new_mesh
+
+    def reset_elements(self) -> None:
+        if not self.is_valid():
+            raise UTIL_functions.BBPException('calling invalid BallanceElementsHelper')
+        
+        # reload all items
+        for elety, elemesh in self.__mElementMap.items():
+            _load_element(elemesh, elety)
+
+    def __write_to_ballance_elements(self) -> None:
+        elements = get_ballance_elements(self.__mAssocScene)
+        elements.clear()
+
+        for elety, elemesh in self.__mElementMap.items():
+            item: BBP_PG_ballance_element = elements.add()
+            item.element_id = get_ballance_element_id(elety)
+            item.mesh_ptr = elemesh
+
+    def __read_from_ballance_element(self) -> None:
+        elements = get_ballance_elements(self.__mAssocScene)
+        self.__mElementMap.clear()
+
+        for item in elements:
+            # check requirements
+            if item.mesh_ptr is None: continue
+            element_type: BallanceElementType | None = get_ballance_element_type_from_id(item.element_id)
+            if element_type is None: continue
+
+            # add into map
+            self.__mElementMap[element_type] = item.mesh_ptr
+
+#endregion
+
+#region Ballance Elements Representation
+
+class BBP_UL_ballance_elements(bpy.types.UIList):
+    def draw_item(self, context, layout: bpy.types.UILayout, data, item: BBP_PG_ballance_element, icon, active_data, active_propname):
+        # check requirements
+        elety: BallanceElementType | None = get_ballance_element_type_from_id(item.element_id)
+        if elety is None or item.mesh_ptr is None: return
+
+        # draw list item
+        layout.label(text = get_ballance_element_name(elety), translate = False)
+        layout.label(text = item.mesh_ptr.name, translate = False, icon = 'MESH_DATA')
+
+class BBP_OT_reset_ballance_elements(bpy.types.Operator):
+    """Reset all Meshes of Loaded Ballance Elements to Original Geometry."""
+    bl_idname = "bbp.reset_ballance_elements"
+    bl_label = "Reset Ballance Elements"
+    bl_options = {'UNDO'}
+    bl_translation_context = 'BBP_OT_reset_ballance_elements'
+    
+    @classmethod
+    def poll(cls, context):
+        return context.scene is not None
+    
+    def execute(self, context):
+        with BallanceElementsHelper(context.scene) as helper:
+            helper.reset_elements()
+        # show a window to let user know, not silence
+        self.report({'INFO'}, 'Reset Ballance elements successfully.')
+        return {'FINISHED'}
+
+class BBP_PT_ballance_elements(bpy.types.Panel):
+    """Show Ballance Elements Properties."""
+    bl_label = "Ballance Elements"
+    bl_idname = "BBP_PT_ballance_elements"
+    bl_space_type = 'PROPERTIES'
+    bl_region_type = 'WINDOW'
+    bl_context = "scene"
+    bl_translation_context = 'BBP_PT_ballance_elements'
+
+    @classmethod
+    def poll(cls, context):
+        return context.scene is not None
+
+    def draw(self, context):
+        layout: bpy.types.UILayout = self.layout
+        target: bpy.types.Scene = context.scene
+        col = layout.column()
+
+        # show restore operator
+        opercol = col.column()
+        opercol.operator(BBP_OT_reset_ballance_elements.bl_idname, icon='LOOP_BACK')
+
+        # show list but not allowed to edit
+        listcol = col.column()
+        listcol.enabled = False
+        listcol.template_list(
+            "BBP_UL_ballance_elements", "", 
+            target, "ballance_elements", 
+            target, "active_ballance_elements",
+            # default row height is a half of the count of all elements
+            # limit the max row height to the the count of all elements
+            rows = _g_ElementCount // 2,
+            maxrows = _g_ElementCount,
+        )
+
+#endregion
+
+def register() -> None:
+    # register all classes
+    bpy.utils.register_class(BBP_PG_ballance_element)
+    bpy.utils.register_class(BBP_UL_ballance_elements)
+    bpy.utils.register_class(BBP_OT_reset_ballance_elements)
+    bpy.utils.register_class(BBP_PT_ballance_elements)
+    
+    # add into scene metadata
+    bpy.types.Scene.ballance_elements = bpy.props.CollectionProperty(type = BBP_PG_ballance_element)
+    bpy.types.Scene.active_ballance_elements = bpy.props.IntProperty()
+
+def unregister() -> None:
+    # del from scene metadata
+    del bpy.types.Scene.active_ballance_elements
+    del bpy.types.Scene.ballance_elements
+
+    bpy.utils.unregister_class(BBP_PT_ballance_elements)
+    bpy.utils.unregister_class(BBP_OT_reset_ballance_elements)
+    bpy.utils.unregister_class(BBP_UL_ballance_elements)
+    bpy.utils.unregister_class(BBP_PG_ballance_element)

bbp_ng/PROP_ballance_map_info.py

@@ -0,0 +1,83 @@
+import bpy
+import typing
+from . import UTIL_functions
+
+class RawBallanceMapInfo():
+    cSectorCount: typing.ClassVar[int] = 1
+
+    mSectorCount: int
+
+    def __init__(self, **kwargs):
+        self.mSectorCount = kwargs.get("mSectorCount", RawBallanceMapInfo.cSectorCount)
+
+    def regulate(self):
+        self.mSectorCount = UTIL_functions.clamp_int(self.mSectorCount, 1, 999)
+
+#region Prop Decl & Getter Setter
+
+class BBP_PG_ballance_map_info(bpy.types.PropertyGroup):
+    sector_count: bpy.props.IntProperty(
+        name = "Sector",
+        description = "The sector count of this Ballance map which is used in exporting map and may be changed when importing map.",
+        default = 1,
+        max = 999, min = 1,
+        soft_max = 8, soft_min = 1,
+        step = 1,
+        translation_context = 'BBP_PG_ballance_map_info/property'
+    ) # type: ignore
+    
+def get_ballance_map_info(scene: bpy.types.Scene) -> BBP_PG_ballance_map_info:
+    return scene.ballance_map_info
+
+def get_raw_ballance_map_info(scene: bpy.types.Scene) -> RawBallanceMapInfo:
+    props: BBP_PG_ballance_map_info = get_ballance_map_info(scene)
+    rawdata: RawBallanceMapInfo = RawBallanceMapInfo()
+
+    rawdata.mSectorCount = props.sector_count
+
+    rawdata.regulate()
+    return rawdata
+
+def set_raw_ballance_map_info(scene: bpy.types.Scene, rawdata: RawBallanceMapInfo) -> None:
+    props: BBP_PG_ballance_map_info = get_ballance_map_info(scene)
+
+    props.sector_count = rawdata.mSectorCount
+
+#endregion
+
+class BBP_PT_ballance_map_info(bpy.types.Panel):
+    """Show Ballance Map Infos."""
+    bl_label = "Ballance Map"
+    bl_idname = "BBP_PT_ballance_map_info"
+    bl_space_type = 'PROPERTIES'
+    bl_region_type = 'WINDOW'
+    bl_context = "scene"
+    bl_translation_context = 'BBP_PT_ballance_map_info'
+    
+    @classmethod
+    def poll(cls, context):
+        return context.scene is not None
+
+    def draw(self, context):
+        layout: bpy.types.UILayout = self.layout
+        target: bpy.types.Scene = context.scene
+        props: BBP_PG_ballance_map_info = get_ballance_map_info(target)
+
+        # show map sector count numberbox
+        layout.prop(props, 'sector_count')
+
+def register() -> None:
+    # register
+    bpy.utils.register_class(BBP_PG_ballance_map_info)
+    bpy.utils.register_class(BBP_PT_ballance_map_info)
+
+    # add into scene metadata
+    bpy.types.Scene.ballance_map_info = bpy.props.PointerProperty(type = BBP_PG_ballance_map_info)
+
+def unregister() -> None:
+    # del from scene metadata
+    del bpy.types.Scene.ballance_map_info
+
+    # unregister
+    bpy.utils.unregister_class(BBP_PG_ballance_map_info)
+    bpy.utils.unregister_class(BBP_PT_ballance_map_info)

bbp_ng/PROP_bme_material.py

@@ -0,0 +1,294 @@
+import bpy
+import typing, enum, copy
+from . import PROP_virtools_material, PROP_virtools_texture
+from . import UTIL_ballance_texture, UTIL_functions, UTIL_icons_manager
+
+#region BME Material Presets
+
+class _BMEMaterialPreset():
+    ## Associated Ballance texture file name, including file extension.
+    mTexName: str
+    ## Predefined mtl preset in virtools material module
+    mRawMtl: PROP_virtools_material.RawVirtoolsMaterial
+
+    def __init__(self, texname: str, rawmtl: PROP_virtools_material.RawVirtoolsMaterial):
+        self.mTexName = texname
+        self.mRawMtl = rawmtl
+
+_g_BMEMaterialPresets: dict[str, _BMEMaterialPreset] = {
+    'FloorSide': _BMEMaterialPreset(
+        'Floor_Side.bmp', 
+        PROP_virtools_material.get_virtools_material_preset(PROP_virtools_material.MaterialPresetType.FloorSide).mData
+    ),
+    'LightingFloorTopBorder': _BMEMaterialPreset(
+        'Floor_Top_Border.bmp', 
+        PROP_virtools_material.get_virtools_material_preset(PROP_virtools_material.MaterialPresetType.FloorSide).mData
+    ),
+    'LightingFloorTopBorderless': _BMEMaterialPreset(
+        'Floor_Top_Borderless.bmp', 
+        PROP_virtools_material.get_virtools_material_preset(PROP_virtools_material.MaterialPresetType.FloorSide).mData
+    ),
+
+    'FloorTopBorder': _BMEMaterialPreset(
+        'Floor_Top_Border.bmp', 
+        PROP_virtools_material.get_virtools_material_preset(PROP_virtools_material.MaterialPresetType.FloorTop).mData
+    ),
+    'FloorTopBorderless': _BMEMaterialPreset(
+        'Floor_Top_Borderless.bmp', 
+        PROP_virtools_material.get_virtools_material_preset(PROP_virtools_material.MaterialPresetType.FloorTop).mData
+    ),
+    'FloorTopFlat': _BMEMaterialPreset(
+        'Floor_Top_Flat.bmp', 
+        PROP_virtools_material.get_virtools_material_preset(PROP_virtools_material.MaterialPresetType.FloorTop).mData
+    ),
+    'FloorTopProfil': _BMEMaterialPreset(
+        'Floor_Top_Profil.bmp', 
+        PROP_virtools_material.get_virtools_material_preset(PROP_virtools_material.MaterialPresetType.FloorTop).mData
+    ),
+    'FloorTopProfilFlat': _BMEMaterialPreset(
+        'Floor_Top_ProfilFlat.bmp', 
+        PROP_virtools_material.get_virtools_material_preset(PROP_virtools_material.MaterialPresetType.FloorTop).mData
+    ),
+
+    'BallPaper': _BMEMaterialPreset(
+        'Ball_Paper.bmp', 
+        PROP_virtools_material.get_virtools_material_preset(PROP_virtools_material.MaterialPresetType.TrafoPaper).mData
+    ),
+
+    'BallStone': _BMEMaterialPreset(
+        'Ball_Stone.bmp', 
+        PROP_virtools_material.get_virtools_material_preset(PROP_virtools_material.MaterialPresetType.TraforWoodStone).mData
+    ),
+    'BallWood': _BMEMaterialPreset(
+        'Ball_Wood.bmp', 
+        PROP_virtools_material.get_virtools_material_preset(PROP_virtools_material.MaterialPresetType.TraforWoodStone).mData
+    ),
+
+    'Rail': _BMEMaterialPreset(
+        'Rail_Environment.bmp', 
+        PROP_virtools_material.get_virtools_material_preset(PROP_virtools_material.MaterialPresetType.Rail).mData
+    ),
+}
+
+#endregion
+
+#region BME Material Define & Visitor
+
+class BBP_PG_bme_material(bpy.types.PropertyGroup):
+    bme_material_name: bpy.props.StringProperty(
+        name = "Name",
+        default = "",
+        translation_context = 'BBP_PG_bme_material/property'
+    ) # type: ignore
+    
+    material_ptr: bpy.props.PointerProperty(
+        name = "Material",
+        type = bpy.types.Material,
+        translation_context = 'BBP_PG_bme_material/property'
+    ) # type: ignore
+
+def get_bme_materials(scene: bpy.types.Scene) -> UTIL_functions.CollectionVisitor[BBP_PG_bme_material]:
+    return UTIL_functions.CollectionVisitor(scene.bme_materials)
+
+#endregion
+
+#region Material Preset Loader
+
+def _load_bme_material_preset(mtl: bpy.types.Material, preset_name: str) -> None:
+    # get preset first
+    preset: _BMEMaterialPreset = _g_BMEMaterialPresets[preset_name]
+
+    # get raw mtl and do a shallow copy
+    # because we will change something later. but do not want to affect preset self.
+    raw_mtl: PROP_virtools_material.RawVirtoolsMaterial = copy.copy(preset.mRawMtl)
+
+    # load ballance texture
+    blctex: bpy.types.Image = UTIL_ballance_texture.load_ballance_texture(preset.mTexName)
+    # apply texture props
+    PROP_virtools_texture.set_raw_virtools_texture(blctex, PROP_virtools_texture.get_ballance_texture_preset(preset.mTexName))
+    # set loaded texture to shallow copied raw mtl
+    raw_mtl.mTexture = blctex
+
+    # set raw mtl
+    PROP_virtools_material.set_raw_virtools_material(mtl, raw_mtl)
+    # apply vt mtl to blender mtl
+    PROP_virtools_material.apply_to_blender_material(mtl)
+
+#endregion
+
+#region BME Material Operation Help Class & Functions
+
+class BMEMaterialsHelper():
+    """
+    The helper of BME materials processing.
+
+    All BME materials operations, including getting or setting, must be manipulated by this class. 
+    You should NOT operate BME Materials property (in Scene) directly.
+
+    This class should only have 1 instance at the same time. This class support `with` syntax to achieve this.
+    This class frequently used in creating BME meshes.
+    """
+    __mSingletonMutex: typing.ClassVar[UTIL_functions.TinyMutex[bpy.types.Scene]] = UTIL_functions.TinyMutex()
+    __mIsValid: bool
+    __mAssocScene: bpy.types.Scene
+    __mMaterialMap: dict[str, bpy.types.Material]
+
+    def __init__(self, assoc: bpy.types.Scene):
+        self.__mMaterialMap = {}
+        self.__mAssocScene = assoc
+        self.__mIsValid = False
+
+        # check singleton
+        BMEMaterialsHelper.__mSingletonMutex.lock(self.__mAssocScene)
+        # set validation and read ballance elements property
+        self.__mIsValid = True
+        self.__read_from_bme_materials()
+
+    def is_valid(self) -> bool:
+        return self.__mIsValid
+    
+    def __enter__(self):
+        return self
+    
+    def __exit__(self, exc_type, exc_value, traceback):
+        self.dispose()
+    
+    def dispose(self) -> None:
+        if self.is_valid():
+            # write to ballance elements property and reset validation
+            self.__write_to_bme_materials()
+            self.__mIsValid = False
+            BMEMaterialsHelper.__mSingletonMutex.unlock(self.__mAssocScene)
+    
+    def get_material(self, preset_name: str) -> bpy.types.Material:
+        if not self.is_valid():
+            raise UTIL_functions.BBPException('calling invalid BMEMaterialsHelper')
+        
+        # get exist one
+        mtl: bpy.types.Material | None = self.__mMaterialMap.get(preset_name, None)
+        if mtl is not None: 
+            return mtl
+
+        # if no existing one, create new one
+        new_mtl_name: str = 'BME' + preset_name
+        new_mtl: bpy.types.Material = bpy.data.materials.new(new_mtl_name)
+
+        _load_bme_material_preset(new_mtl, preset_name)
+        self.__mMaterialMap[preset_name] = new_mtl
+        return new_mtl
+
+    def reset_materials(self) -> None:
+        if not self.is_valid():
+            raise UTIL_functions.BBPException('calling invalid BMEMaterialsHelper')
+        
+        # load all items
+        for preset_name, mtl in self.__mMaterialMap.items():
+            _load_bme_material_preset(mtl, preset_name)
+
+    def __write_to_bme_materials(self) -> None:
+        mtls = get_bme_materials(self.__mAssocScene)
+        mtls.clear()
+
+        for preset_name, mtl in self.__mMaterialMap.items():
+            item: BBP_PG_bme_material = mtls.add()
+            item.bme_material_name = preset_name
+            item.material_ptr = mtl
+
+    def __read_from_bme_materials(self) -> None:
+        mtls = get_bme_materials(self.__mAssocScene)
+        self.__mMaterialMap.clear()
+
+        for item in mtls:
+            # check requirements
+            if item.material_ptr is None: continue
+            # add into map
+            self.__mMaterialMap[item.bme_material_name] = item.material_ptr
+
+#endregion
+
+#region BME Materials Representation
+
+class BBP_UL_bme_materials(bpy.types.UIList):
+    def draw_item(self, context, layout: bpy.types.UILayout, data, item: BBP_PG_bme_material, icon, active_data, active_propname):
+        # check requirements
+        if item.material_ptr is None: return
+        # draw list item
+        layout.label(text = item.bme_material_name, translate = False)
+        layout.label(text = item.material_ptr.name, translate = False, icon = 'MATERIAL')
+
+class BBP_OT_reset_bme_materials(bpy.types.Operator):
+    """Reset all BME Materials to Default Settings."""
+    bl_idname = "bbp.reset_bme_materials"
+    bl_label = "Reset BME Materials"
+    bl_options = {'UNDO'}
+    bl_translation_context = 'BBP_OT_reset_bme_materials'
+    
+    @classmethod
+    def poll(cls, context):
+        return context.scene is not None
+    
+    def execute(self, context):
+        with BMEMaterialsHelper(context.scene) as helper:
+            helper.reset_materials()
+        # show a window to let user know, not silence
+        self.report({'INFO'}, 'Reset BME materials successfully.')
+        return {'FINISHED'}
+
+class BBP_PT_bme_materials(bpy.types.Panel):
+    """Show BME Materials Properties."""
+    bl_label = "BME Materials"
+    bl_idname = "BBP_PT_bme_materials"
+    bl_space_type = 'PROPERTIES'
+    bl_region_type = 'WINDOW'
+    bl_context = "scene"
+    bl_translation_context = 'BBP_PT_bme_materials'
+
+    @classmethod
+    def poll(cls, context):
+        return context.scene is not None
+
+    def draw(self, context):
+        layout: bpy.types.UILayout = self.layout
+        target: bpy.types.Scene = context.scene
+        col = layout.column()
+
+        # show restore operator
+        opercol = col.column()
+        opercol.operator(BBP_OT_reset_bme_materials.bl_idname, icon='LOOP_BACK')
+
+        # show list but not allowed to edit
+        listcol = col.column()
+        listcol.enabled = False
+        listcol.template_list(
+            "BBP_UL_bme_materials", "", 
+            target, "bme_materials", 
+            target, "active_bme_materials",
+            # default row height is a half of the count of all presets
+            # limit the max row height to the the count of all presets
+            rows = len(_g_BMEMaterialPresets) // 2,
+            maxrows = len(_g_BMEMaterialPresets),
+        )
+
+#endregion
+
+def register() -> None:
+    # register all classes
+    bpy.utils.register_class(BBP_PG_bme_material)
+    bpy.utils.register_class(BBP_UL_bme_materials)
+    bpy.utils.register_class(BBP_OT_reset_bme_materials)
+    bpy.utils.register_class(BBP_PT_bme_materials)
+    
+    # add into scene metadata
+    bpy.types.Scene.bme_materials = bpy.props.CollectionProperty(type = BBP_PG_bme_material)
+    bpy.types.Scene.active_bme_materials = bpy.props.IntProperty()
+
+def unregister() -> None:
+    # del from scene metadata
+    del bpy.types.Scene.active_bme_materials
+    del bpy.types.Scene.bme_materials
+
+    bpy.utils.unregister_class(BBP_PT_bme_materials)
+    bpy.utils.unregister_class(BBP_OT_reset_bme_materials)
+    bpy.utils.unregister_class(BBP_UL_bme_materials)
+    bpy.utils.unregister_class(BBP_PG_bme_material)
+

bbp_ng/PROP_preferences.py

@@ -0,0 +1,63 @@
+import bpy
+import os, typing
+from . import UTIL_naming_convension
+
+class RawPreferences():
+    cBallanceTextureFolder: typing.ClassVar[str] = ""
+    cNoComponentCollection: typing.ClassVar[str] = ""
+
+    mBallanceTextureFolder: str
+    mNoComponentCollection: str
+
+    def __init__(self, **kwargs):
+        self.mBallanceTextureFolder = kwargs.get("mBallanceTextureFolder", "")
+        self.mNoComponentCollection = kwargs.get("mNoComponentCollection", "")
+
+    def has_valid_blc_tex_folder(self) -> bool:
+        return os.path.isdir(self.mBallanceTextureFolder)
+
+class BBPPreferences(bpy.types.AddonPreferences):
+    bl_idname = __package__
+    
+    ballance_texture_folder: bpy.props.StringProperty(
+        name = "Ballance Texture Folder",
+        description = "The path to folder which will be used by this plugin to get external Ballance texture.",
+        subtype = 'DIR_PATH',
+        default = RawPreferences.cBallanceTextureFolder,
+        translation_context = 'BBPPreferences/property'
+    ) # type: ignore
+    
+    no_component_collection: bpy.props.StringProperty(
+        name = "No Component Collection",
+        description = "When importing, it is the name of collection where objects store will not be saved as component. When exporting, all forced no component objects will be stored in this name represented collection",
+        default = RawPreferences.cNoComponentCollection,
+        translation_context = 'BBPPreferences/property'
+    ) # type: ignore
+    
+    def draw(self, context):
+        layout: bpy.types.UILayout = self.layout
+        
+        row = layout.row()
+        col = row.column()
+        col.label(text="Ballance Texture Folder", text_ctxt='BBPPreferences/draw')
+        col.prop(self, "ballance_texture_folder", text = "")
+        col.label(text="No Component Collection", text_ctxt='BBPPreferences/draw')
+        col.prop(self, "no_component_collection", text = "")
+
+def get_preferences() -> BBPPreferences:
+    return bpy.context.preferences.addons[__package__].preferences
+
+def get_raw_preferences() -> RawPreferences:
+    pref: BBPPreferences = get_preferences()
+    rawdata: RawPreferences = RawPreferences()
+
+    rawdata.mBallanceTextureFolder = pref.ballance_texture_folder
+    rawdata.mNoComponentCollection = pref.no_component_collection
+
+    return rawdata
+
+def register() -> None:
+    bpy.utils.register_class(BBPPreferences)
+
+def unregister() -> None:
+    bpy.utils.unregister_class(BBPPreferences)

bbp_ng/PROP_ptrprop_resolver.py

@@ -0,0 +1,261 @@
+import bpy
+from bpy.types import Context, Event
+from . import UTIL_functions, UTIL_virtools_types
+
+## Intent
+#  Operator is not allowed to register Pointer Properties.
+#  The solution is register pointer properties in Scene and reference it when drawing operator window.
+#  This module contains all pointer properties used by other operators.
+
+#region Blender Type Defines
+
+class BBP_PG_bmap_encoding(bpy.types.PropertyGroup):
+    encoding: bpy.props.StringProperty(
+        name = "Encoding",
+        description = "The name of BMap used encoding.",
+        default = "",
+        translation_context = 'BBP_PG_bmap_encoding/property'
+    ) # type: ignore
+
+class BBP_UL_bmap_encoding(bpy.types.UIList):
+    def draw_item(self, context, layout: bpy.types.UILayout, data, item: BBP_PG_bmap_encoding, icon, active_data, active_propname):
+        layout.prop(item, 'encoding', emboss = False, text = '', icon = 'FONT_DATA')
+
+class BBP_PG_ptrprop_resolver(bpy.types.PropertyGroup):
+    rail_uv_material: bpy.props.PointerProperty(
+        name = "Material",
+        description = "The material used for rail",
+        type = bpy.types.Material,
+        translation_context = 'BBP_PG_ptrprop_resolver/property'
+    ) # type: ignore
+    
+    export_collection: bpy.props.PointerProperty(
+        name = "Collection",
+        description = "The collection exported. Nested collections allowed.",
+        type = bpy.types.Collection,
+        translation_context = 'BBP_PG_ptrprop_resolver/property'
+    ) # type: ignore
+    
+    export_object: bpy.props.PointerProperty(
+        name = "Object",
+        description = "The object exported",
+        type = bpy.types.Object,
+        translation_context = 'BBP_PG_ptrprop_resolver/property'
+    ) # type: ignore
+
+    # TR: Properties not showen should not have name and desc.
+    ioport_encodings: bpy.props.CollectionProperty(type = BBP_PG_bmap_encoding) # type: ignore
+    active_ioport_encodings: bpy.props.IntProperty() # type: ignore
+
+#endregion
+
+def get_ptrprop_resolver(scene: bpy.types.Scene) -> BBP_PG_ptrprop_resolver:
+    return scene.bbp_ptrprop_resolver
+
+def get_ioport_encodings(scene: bpy.types.Scene) -> UTIL_functions.CollectionVisitor[BBP_PG_bmap_encoding]:
+    return UTIL_functions.CollectionVisitor(get_ptrprop_resolver(scene).ioport_encodings)
+def get_active_ioport_encoding(scene: bpy.types.Scene) -> int:
+    return get_ptrprop_resolver(scene).active_ioport_encodings
+def set_active_ioport_encoding(scene: bpy.types.Scene, val: int) -> None:
+    get_ptrprop_resolver(scene).active_ioport_encodings = val
+
+#region Blender Operator Defines for Encodings
+
+class BBP_OT_add_ioport_encodings(bpy.types.Operator):
+    """Add item at the tail of encodings list used by BMap for Virtools file read and write."""
+    bl_idname = "bbp.add_ioport_encodings"
+    bl_label = "Add in Encodings List"
+    bl_options = {'UNDO'}
+    bl_translation_context = 'BBP_OT_add_ioport_encodings'
+
+    @classmethod
+    def poll(cls, context: bpy.types.Context) -> bool:
+        return True
+
+    def execute(self, context):
+        encodings = get_ioport_encodings(context.scene)
+        encodings.add()
+        return {'FINISHED'}
+
+class BBP_OT_rm_ioport_encodings(bpy.types.Operator):
+    """Remove selected item in encodings list used by BMap for Virtools file read and write."""
+    bl_idname = "bbp.rm_ioport_encodings"
+    bl_label = "Remove from Encodings List"
+    bl_options = {'UNDO'}
+    bl_translation_context = 'BBP_OT_rm_ioport_encodings'
+
+    @classmethod
+    def poll(cls, context: bpy.types.Context) -> bool:
+        encodings = get_ioport_encodings(context.scene)
+        index = get_active_ioport_encoding(context.scene)
+        return index >= 0 and index < len(encodings)
+
+    def execute(self, context):
+        # delete selected item
+        encodings = get_ioport_encodings(context.scene)
+        index = get_active_ioport_encoding(context.scene)
+        encodings.remove(index)
+        # try to correct selected item
+        if index >= len(encodings): index = len(encodings) - 1
+        if index < 0: index = 0
+        set_active_ioport_encoding(context.scene, index)
+        return {'FINISHED'}
+
+class BBP_OT_up_ioport_encodings(bpy.types.Operator):
+    """Move selected item up in encodings list used by BMap for Virtools file read and write."""
+    bl_idname = "bbp.up_ioport_encodings"
+    bl_label = "Move Up in Encodings List"
+    bl_options = {'UNDO'}
+    bl_translation_context = 'BBP_OT_up_ioport_encodings'
+
+    @classmethod
+    def poll(cls, context: bpy.types.Context) -> bool:
+        encodings = get_ioport_encodings(context.scene)
+        index = get_active_ioport_encoding(context.scene)
+        return index >= 1 and index < len(encodings)
+
+    def execute(self, context):
+        encodings = get_ioport_encodings(context.scene)
+        index = get_active_ioport_encoding(context.scene)
+        encodings.move(index, index - 1)
+        set_active_ioport_encoding(context.scene, index - 1)
+        return {'FINISHED'}
+
+class BBP_OT_down_ioport_encodings(bpy.types.Operator):
+    """Move selected item down in encodings list used by BMap for Virtools file read and write."""
+    bl_idname = "bbp.down_ioport_encodings"
+    bl_label = "Move Down in Encodings List"
+    bl_options = {'UNDO'}
+    bl_translation_context = 'BBP_OT_down_ioport_encodings'
+
+    @classmethod
+    def poll(cls, context: bpy.types.Context) -> bool:
+        encodings = get_ioport_encodings(context.scene)
+        index = get_active_ioport_encoding(context.scene)
+        return index >= 0 and index < len(encodings) - 1
+
+    def execute(self, context):
+        encodings = get_ioport_encodings(context.scene)
+        index = get_active_ioport_encoding(context.scene)
+        encodings.move(index, index + 1)
+        set_active_ioport_encoding(context.scene, index + 1)
+        return {'FINISHED'}
+
+class BBP_OT_clear_ioport_encodings(bpy.types.Operator):
+    """Clear the encodings list used by BMap for Virtools file read and write."""
+    bl_idname = "bbp.clear_ioport_encodings"
+    bl_label = "Clear Encodings List"
+    bl_options = {'UNDO'}
+    bl_translation_context = 'BBP_OT_clear_ioport_encodings'
+
+    @classmethod
+    def poll(cls, context: bpy.types.Context) -> bool:
+        return True
+
+    def invoke(self, context, event):
+        wm = context.window_manager
+        return wm.invoke_confirm(self, event)
+    
+    def execute(self, context):
+        encodings = get_ioport_encodings(context.scene)
+        encodings.clear()
+        set_active_ioport_encoding(context.scene, 0)
+        return {'FINISHED'}
+
+#endregion
+
+class PropsVisitor():
+    """
+    When outside code want to fetch or draw properties defined in ptrprop_resolver,
+    they should create the instance of this class with given associated scene instance first.
+    Then use this class provided member function to draw or fetch these properties.
+    The function located in this module should not be called directly!
+    """
+
+    __mAssocScene: bpy.types.Scene
+
+    def __init__(self, assoc_scene: bpy.types.Scene):
+        self.__mAssocScene = assoc_scene
+
+    def get_rail_uv_material(self) -> bpy.types.Material:
+        return get_ptrprop_resolver(self.__mAssocScene).rail_uv_material
+    def draw_rail_uv_material(self, layout: bpy.types.UILayout) -> None:
+        layout.prop(get_ptrprop_resolver(self.__mAssocScene), 'rail_uv_material')
+
+    def get_export_collection(self) -> bpy.types.Collection:
+        return get_ptrprop_resolver(self.__mAssocScene).export_collection
+    def draw_export_collection(self, layout: bpy.types.UILayout) -> None:
+        layout.prop(get_ptrprop_resolver(self.__mAssocScene), 'export_collection')
+
+    def get_export_object(self) -> bpy.types.Object:
+        return get_ptrprop_resolver(self.__mAssocScene).export_object
+    def draw_export_object(self, layout: bpy.types.UILayout) -> None:
+        layout.prop(get_ptrprop_resolver(self.__mAssocScene), 'export_object')
+
+    def get_ioport_encodings(self) -> tuple[str, ...]:
+        encodings = get_ioport_encodings(self.__mAssocScene)
+        return tuple(i.encoding for i in encodings)
+    def draw_ioport_encodings(self, layout: bpy.types.UILayout) -> None:
+        target = get_ptrprop_resolver(self.__mAssocScene)
+        row = layout.row()
+
+        # draw main list
+        row.template_list(
+            "BBP_UL_bmap_encoding", "", 
+            target, "ioport_encodings",
+            target, "active_ioport_encodings",
+            rows = 6, maxrows = 6,
+            sort_reverse = False, sort_lock = True # disable sort feature because the order od this encoding list is crucial
+        )
+
+        # draw sidebar
+        col = row.column(align=True)
+        col.operator(BBP_OT_add_ioport_encodings.bl_idname, icon='ADD', text='')
+        col.operator(BBP_OT_rm_ioport_encodings.bl_idname, icon='REMOVE', text='')
+        col.separator()
+        col.operator(BBP_OT_up_ioport_encodings.bl_idname, icon='TRIA_UP', text='')
+        col.operator(BBP_OT_down_ioport_encodings.bl_idname, icon='TRIA_DOWN', text='')
+        col.separator()
+        col.operator(BBP_OT_clear_ioport_encodings.bl_idname, icon='TRASH', text='')
+
+@bpy.app.handlers.persistent
+def _ioport_encodings_initializer(file_path: str):
+    # if we can fetch property, and it is empty after loading file
+    # we fill it with default value
+    encodings = get_ioport_encodings(bpy.context.scene)
+    if len(encodings) == 0:
+        for default_enc in UTIL_virtools_types.g_PyBMapDefaultEncodings:
+            item = encodings.add()
+            item.encoding = default_enc
+
+def register() -> None:
+    bpy.utils.register_class(BBP_PG_bmap_encoding)
+    bpy.utils.register_class(BBP_UL_bmap_encoding)
+    bpy.utils.register_class(BBP_PG_ptrprop_resolver)
+
+    # register ioport encodings default value
+    bpy.app.handlers.load_post.append(_ioport_encodings_initializer)
+
+    bpy.utils.register_class(BBP_OT_add_ioport_encodings)
+    bpy.utils.register_class(BBP_OT_rm_ioport_encodings)
+    bpy.utils.register_class(BBP_OT_up_ioport_encodings)
+    bpy.utils.register_class(BBP_OT_down_ioport_encodings)
+    bpy.utils.register_class(BBP_OT_clear_ioport_encodings)
+
+    bpy.types.Scene.bbp_ptrprop_resolver = bpy.props.PointerProperty(type = BBP_PG_ptrprop_resolver)
+
+def unregister() -> None:
+    del bpy.types.Scene.bbp_ptrprop_resolver
+
+    bpy.utils.unregister_class(BBP_OT_clear_ioport_encodings)
+    bpy.utils.unregister_class(BBP_OT_down_ioport_encodings)
+    bpy.utils.unregister_class(BBP_OT_up_ioport_encodings)
+    bpy.utils.unregister_class(BBP_OT_rm_ioport_encodings)
+    bpy.utils.unregister_class(BBP_OT_add_ioport_encodings)
+
+    # unregister ioport encodings default value
+    bpy.app.handlers.load_post.remove(_ioport_encodings_initializer)
+
+    bpy.utils.unregister_class(BBP_PG_ptrprop_resolver)
+    bpy.utils.unregister_class(BBP_UL_bmap_encoding)
+    bpy.utils.unregister_class(BBP_PG_bmap_encoding)

bbp_ng/PROP_virtools_group.py

@@ -0,0 +1,436 @@
+import bpy
+import typing, enum
+from . import UTIL_functions, UTIL_icons_manager
+
+#region Virtools Groups Define & Help Class
+
+class BBP_PG_virtools_group(bpy.types.PropertyGroup):
+    group_name: bpy.props.StringProperty(
+        name = "Group Name",
+        default = "",
+        translation_context = 'BBP_PG_virtools_group/property'
+    ) # type: ignore
+
+def get_virtools_groups(obj: bpy.types.Object) -> UTIL_functions.CollectionVisitor[BBP_PG_virtools_group]:
+    return UTIL_functions.CollectionVisitor(obj.virtools_groups)
+
+def get_active_virtools_groups(obj: bpy.types.Object) -> int:
+    return obj.active_virtools_groups
+
+def set_active_virtools_groups(obj: bpy.types.Object, val: int) -> None:
+    obj.active_virtools_groups = val
+
+class VirtoolsGroupsHelper():
+    """
+    A helper for object's Virtools groups adding, removal and checking.
+
+    All Virtools group operations should be done by this class.
+    Do NOT manipulate object's Virtools group properties directly.
+    """
+    __mSingletonMutex: typing.ClassVar[UTIL_functions.TinyMutex[bpy.types.Object]] = UTIL_functions.TinyMutex()
+    __mIsValid: bool
+    __mNoChange: bool ##< A bool indicate whether any change happended during lifetime. If no change, skip the writing when exiting.
+    __mAssocObj: bpy.types.Object
+    __mGroupsSet: set[str]
+    
+    def __init__(self, assoc: bpy.types.Object):
+        self.__mGroupsSet = set()
+        self.__mAssocObj = assoc
+        self.__mNoChange = True
+        self.__mIsValid = False
+        
+        # check singleton
+        VirtoolsGroupsHelper.__mSingletonMutex.lock(self.__mAssocObj)
+        # set validation and read ballance elements property
+        self.__mIsValid = True
+        self.__read_from_virtools_groups()
+    
+    def is_valid(self) -> bool:
+        return self.__mIsValid
+    
+    def __enter__(self):
+        return self
+    
+    def __exit__(self, exc_type, exc_value, traceback):
+        self.dispose()
+    
+    def dispose(self) -> None:
+        if self.is_valid():
+            # if have changes,
+            # write to ballance elements property and reset validation
+            if not self.__mNoChange:
+                self.__write_to_virtools_groups()
+            self.__mIsValid = False
+            VirtoolsGroupsHelper.__mSingletonMutex.unlock(self.__mAssocObj)
+    
+    def __check_valid(self) -> None:
+        if not self.is_valid():
+            raise UTIL_functions.BBPException('calling invalid VirtoolsGroupsHelper')
+    
+    def add_group(self, gname: str) -> None:
+        self.__check_valid()
+        self.__mNoChange = False
+        self.__mGroupsSet.add(gname)
+    
+    def add_groups(self, gnames: typing.Iterable[str]) -> None:
+        self.__check_valid()
+        self.__mNoChange = False
+        self.__mGroupsSet.update(gnames)
+    
+    def remove_group(self, gname: str) -> None:
+        self.__check_valid()
+        self.__mNoChange = False
+        self.__mGroupsSet.discard(gname)
+    
+    def remove_groups(self, gnames: typing.Iterable[str]) -> None:
+        self.__check_valid()
+        self.__mNoChange = False
+        for gname in gnames:
+            self.__mGroupsSet.discard(gname)
+    
+    def contain_group(self, gname: str) -> bool:
+        self.__check_valid()
+        return gname in self.__mGroupsSet
+    
+    def contain_groups(self, gnames: typing.Iterable[str]) -> bool:
+        """
+        Check existing intersection between group names and given collection.
+
+        In other words, check whether group name of given paramter is in group names with OR operator.
+
+        @param gnames[in] Iterable group names to check.
+        @return return True if the length of the intersection between group names and given group names is not zero.
+        """
+        self.__check_valid()
+        for gname in gnames:
+            if gname in self.__mGroupsSet:
+                return True
+        return False
+    
+    def intersect_groups(self, gnames: set[str]) -> set[str]:
+        self.__check_valid()
+        return self.__mGroupsSet.intersection(gnames)
+    
+    def iterate_groups(self) -> typing.Iterator[str]:
+        self.__check_valid()
+        return iter(self.__mGroupsSet)
+
+    def clear_groups(self) -> None:
+        self.__check_valid()
+        self.__mNoChange = False
+        self.__mGroupsSet.clear()
+
+    def get_count(self) -> int:
+        self.__check_valid()
+        return len(self.__mGroupsSet)
+    
+    def __write_to_virtools_groups(self) -> None:
+        groups = get_virtools_groups(self.__mAssocObj)
+        sel: int = get_active_virtools_groups(self.__mAssocObj)
+        groups.clear()
+        
+        for gname in self.__mGroupsSet:
+            item: BBP_PG_virtools_group = groups.add()
+            item.group_name = gname
+        
+        # restore selection if necessary
+        if sel >= len(self.__mGroupsSet):
+            sel = len(self.__mGroupsSet) - 1
+        if sel < 0:
+            sel = 0
+        set_active_virtools_groups(self.__mAssocObj, sel)
+    
+    def __read_from_virtools_groups(self) -> None:
+        groups = get_virtools_groups(self.__mAssocObj)
+        self.__mGroupsSet.clear()
+        
+        for item in groups:
+            self.__mGroupsSet.add(item.group_name)
+
+#endregion
+
+#region Preset Group Names
+
+class VirtoolsGroupsPreset(enum.Enum):
+    Sector_01 = "Sector_01"
+    Sector_02 = "Sector_02"
+    Sector_03 = "Sector_03"
+    Sector_04 = "Sector_04"
+    Sector_05 = "Sector_05"
+    Sector_06 = "Sector_06"
+    Sector_07 = "Sector_07"
+    Sector_08 = "Sector_08"
+    
+    P_Extra_Life = "P_Extra_Life"
+    P_Extra_Point = "P_Extra_Point"
+    P_Trafo_Paper = "P_Trafo_Paper"
+    P_Trafo_Stone = "P_Trafo_Stone"
+    P_Trafo_Wood = "P_Trafo_Wood"
+    P_Ball_Paper = "P_Ball_Paper"
+    P_Ball_Stone = "P_Ball_Stone"
+    P_Ball_Wood = "P_Ball_Wood"
+    P_Box = "P_Box"
+    P_Dome = "P_Dome"
+    P_Modul_01 = "P_Modul_01"
+    P_Modul_03 = "P_Modul_03"
+    P_Modul_08 = "P_Modul_08"
+    P_Modul_17 = "P_Modul_17"
+    P_Modul_18 = "P_Modul_18"
+    P_Modul_19 = "P_Modul_19"
+    P_Modul_25 = "P_Modul_25"
+    P_Modul_26 = "P_Modul_26"
+    P_Modul_29 = "P_Modul_29"
+    P_Modul_30 = "P_Modul_30"
+    P_Modul_34 = "P_Modul_34"
+    P_Modul_37 = "P_Modul_37"
+    P_Modul_41 = "P_Modul_41"
+    
+    PS_Levelstart = "PS_Levelstart"
+    PE_Levelende = "PE_Levelende"
+    PC_Checkpoints = "PC_Checkpoints"
+    PR_Resetpoints = "PR_Resetpoints"
+    
+    Sound_HitID_01 = "Sound_HitID_01"
+    Sound_RollID_01 = "Sound_RollID_01"
+    Sound_HitID_02 = "Sound_HitID_02"
+    Sound_RollID_02 = "Sound_RollID_02"
+    Sound_HitID_03 = "Sound_HitID_03"
+    Sound_RollID_03 = "Sound_RollID_03"
+    
+    DepthTestCubes = "DepthTestCubes"
+    
+    Phys_Floors = "Phys_Floors"
+    Phys_FloorRails = "Phys_FloorRails"
+    Phys_FloorStopper = "Phys_FloorStopper"
+    
+    Shadow = "Shadow"
+
+_g_VtGrpPresetValues: tuple[str] = tuple(map(lambda x: x.value, VirtoolsGroupsPreset))
+
+## Some of group names are not matched with icon name
+#  So we create a convertion map to convert them.
+_g_GroupIconNameConvMap: dict[str, str] = {
+    "PS_Levelstart": "PS_FourFlames",
+    "PE_Levelende": "PE_Balloon",
+    "PC_Checkpoints": "PC_TwoFlames",
+    "PR_Resetpoints": "PR_Resetpoint",
+
+    "Sound_HitID_01": "SoundID_01",
+    "Sound_RollID_01": "SoundID_01",
+    "Sound_HitID_02": "SoundID_02",
+    "Sound_RollID_02": "SoundID_02",
+    "Sound_HitID_03": "SoundID_03",
+    "Sound_RollID_03": "SoundID_03"
+}
+def _get_group_icon_by_name(gp_name: str) -> int:
+    # try converting group name
+    # if not found, return self
+    gp_name = _g_GroupIconNameConvMap.get(gp_name, gp_name)
+    
+    # get from extra group icon first
+    value: int | None = UTIL_icons_manager.get_group_icon(gp_name)
+    if value is not None: return value
+
+    # if failed, get from component. if still failed, return empty icon
+    value = UTIL_icons_manager.get_component_icon(gp_name)
+    if value is not None: return value
+    else: return UTIL_icons_manager.get_empty_icon()
+# blender group name prop helper
+_g_EnumHelper_Group: UTIL_functions.EnumPropHelper = UTIL_functions.EnumPropHelper(
+    VirtoolsGroupsPreset,
+    lambda x: x.value,  # member is string self
+    lambda x: VirtoolsGroupsPreset(x),   # convert directly because it is StrEnum.
+    lambda x: x.value,
+    lambda _: '',
+    lambda x: _get_group_icon_by_name(x.value)
+)
+
+class SharedGroupNameInputProperties():
+    group_name_source: bpy.props.EnumProperty(
+        name = "Group Name Source",
+        items = (
+            ('DEFINED', "Predefined", "Pre-defined group name."),
+            ('CUSTOM', "Custom", "User specified group name."),
+        ),
+        translation_context = 'BBP/PROP_virtools_grourp.SharedGroupNameInputProperties/property'
+    ) # type: ignore
+    
+    preset_group_name: bpy.props.EnumProperty(
+        name = "Group Name",
+        description = "Pick vanilla Ballance group name.",
+        items = _g_EnumHelper_Group.generate_items(),
+        translation_context = 'BBP/PROP_virtools_grourp.SharedGroupNameInputProperties/property'
+    ) # type: ignore
+    
+    custom_group_name: bpy.props.StringProperty(
+        name = "Custom Group Name",
+        description = "Input your custom group name.",
+        default = "",
+        translation_context = 'BBP/PROP_virtools_grourp.SharedGroupNameInputProperties/property'
+    ) # type: ignore
+    
+    def draw_group_name_input(self, layout: bpy.types.UILayout) -> None:
+        layout.prop(self, 'group_name_source', expand = True)
+        if (self.group_name_source == 'CUSTOM'):
+            layout.prop(self, 'custom_group_name')
+        else:
+            layout.prop(self, 'preset_group_name')
+    
+    def general_get_group_name(self) -> str:
+        if self.group_name_source == 'CUSTOM':
+            return self.custom_group_name
+        else:
+            return _g_EnumHelper_Group.get_selection(self.preset_group_name).value
+
+#endregion
+
+#region Display Panel and Simple Operator
+
+class BBP_UL_virtools_groups(bpy.types.UIList):
+    def draw_item(self, context, layout: bpy.types.UILayout, data, item: BBP_PG_virtools_group, icon, active_data, active_propname):
+        layout.label(text = item.group_name, translate = False, icon_value = _get_group_icon_by_name(item.group_name))
+
+class BBP_OT_add_virtools_group(bpy.types.Operator, SharedGroupNameInputProperties):
+    """Add a Virtools Group for Active Object."""
+    bl_idname = "bbp.add_virtools_groups"
+    bl_label = "Add to Virtools Groups"
+    bl_options = {'UNDO'}
+    bl_translation_context = 'BBP_OT_add_virtools_group'
+    
+    @classmethod
+    def poll(cls, context: bpy.types.Context):
+        return context.object is not None
+    
+    def invoke(self, context, event):
+        wm = context.window_manager
+        return wm.invoke_props_dialog(self)
+    
+    def execute(self, context):
+        # add group
+        obj = typing.cast(bpy.types.Object, context.object)
+        with VirtoolsGroupsHelper(obj) as hlp:
+            hlp.add_group(self.general_get_group_name())
+        return {'FINISHED'}
+    
+    def draw(self, context):
+        self.draw_group_name_input(self.layout)
+
+class BBP_OT_rm_virtools_group(bpy.types.Operator):
+    """Remove a Virtools Group for Active Object."""
+    bl_idname = "bbp.rm_virtools_groups"
+    bl_label = "Remove from Virtools Groups"
+    bl_options = {'UNDO'}
+    bl_translation_context = 'BBP_OT_rm_virtools_group'
+    
+    ## This class is slightly unique.
+    #  Because we need get user selected group name first.
+    #  Then pass it to helper.
+    
+    @classmethod
+    def poll(cls, context: bpy.types.Context):
+        if context.object is None:
+            return False
+        
+        obj = context.object
+        gp = get_virtools_groups(obj)
+        active_gp = get_active_virtools_groups(obj)
+        return active_gp >= 0 and active_gp < len(gp)
+    
+    def execute(self, context):
+        # get selected group name first
+        obj = typing.cast(bpy.types.Object, context.object)
+        groups = get_virtools_groups(obj)
+        item = groups[get_active_virtools_groups(obj)]
+        gname: str = item.group_name
+        # then delete it
+        with VirtoolsGroupsHelper(obj) as hlp:
+            hlp.remove_group(gname)
+        
+        return {'FINISHED'}
+
+class BBP_OT_clear_virtools_groups(bpy.types.Operator):
+    """Clear All Virtools Group for Active Object."""
+    bl_idname = "bbp.clear_virtools_groups"
+    bl_label = "Clear Virtools Groups"
+    bl_options = {'UNDO'}
+    bl_translation_context = 'BBP_OT_clear_virtools_groups'
+    
+    @classmethod
+    def poll(cls, context: bpy.types.Context):
+        return context.object is not None
+    
+    def invoke(self, context, event):
+        wm = context.window_manager
+        return wm.invoke_confirm(self, event)
+    
+    def execute(self, context):
+        obj = typing.cast(bpy.types.Object, context.object)
+        with VirtoolsGroupsHelper(obj) as hlp:
+            hlp.clear_groups()
+        return {'FINISHED'}
+
+class BBP_PT_virtools_groups(bpy.types.Panel):
+    """Show Virtools Groups Properties."""
+    bl_label = "Virtools Groups"
+    bl_idname = "BBP_PT_virtools_groups"
+    bl_space_type = 'PROPERTIES'
+    bl_region_type = 'WINDOW'
+    bl_context = "object"
+    bl_translation_context = 'BBP_PT_virtools_groups'
+    
+    @classmethod
+    def poll(cls, context):
+        return context.object is not None
+    
+    def draw(self, context):
+        layout = self.layout
+        target = typing.cast(bpy.types.Object, context.active_object)
+
+        # notify on non-mesh object
+        if target.type != 'MESH':
+            layout.label(
+                text='Virtools Group is invalid on non-mesh object!', icon='ERROR',
+                text_ctxt='BBP_PT_virtools_groups/draw')
+
+        # draw main body
+        row = layout.row()
+        row.template_list(
+            "BBP_UL_virtools_groups", "", 
+            target, "virtools_groups",
+            target, "active_virtools_groups",
+            rows = 6,
+            maxrows = 6,
+        )
+        
+        col = row.column(align=True)
+        col.operator(BBP_OT_add_virtools_group.bl_idname, icon='ADD', text="")
+        col.operator(BBP_OT_rm_virtools_group.bl_idname, icon='REMOVE', text="")
+        col.separator()
+        col.operator(BBP_OT_clear_virtools_groups.bl_idname, icon='TRASH', text="")
+
+#endregion
+
+def register() -> None:
+    # register all classes
+    bpy.utils.register_class(BBP_PG_virtools_group)
+    bpy.utils.register_class(BBP_UL_virtools_groups)
+    bpy.utils.register_class(BBP_OT_add_virtools_group)
+    bpy.utils.register_class(BBP_OT_rm_virtools_group)
+    bpy.utils.register_class(BBP_OT_clear_virtools_groups)
+    bpy.utils.register_class(BBP_PT_virtools_groups)
+    
+    # add into object metadata
+    bpy.types.Object.virtools_groups = bpy.props.CollectionProperty(type = BBP_PG_virtools_group)
+    bpy.types.Object.active_virtools_groups = bpy.props.IntProperty()
+
+def unregister() -> None:
+    # del from object metadata
+    del bpy.types.Object.active_virtools_groups
+    del bpy.types.Object.virtools_groups
+    
+    bpy.utils.unregister_class(BBP_PT_virtools_groups)
+    bpy.utils.unregister_class(BBP_OT_clear_virtools_groups)
+    bpy.utils.unregister_class(BBP_OT_rm_virtools_group)
+    bpy.utils.unregister_class(BBP_OT_add_virtools_group)
+    bpy.utils.unregister_class(BBP_UL_virtools_groups)
+    bpy.utils.unregister_class(BBP_PG_virtools_group)

bbp_ng/PROP_virtools_light.py

@@ -0,0 +1,334 @@
+import bpy, mathutils
+from bpy.types import Context
+import typing, math
+from . import UTIL_functions, UTIL_virtools_types
+
+# Raw Data
+
+class RawVirtoolsLight():
+    # Class member
+
+    mType: UTIL_virtools_types.VXLIGHT_TYPE
+    mColor: UTIL_virtools_types.VxColor
+
+    mConstantAttenuation: float
+    mLinearAttenuation: float
+    mQuadraticAttenuation: float
+
+    mRange: float
+
+    mHotSpot: float
+    mFalloff: float
+    mFalloffShape: float
+
+    # Class member default value
+
+    cDefaultType: typing.ClassVar[UTIL_virtools_types.VXLIGHT_TYPE] = UTIL_virtools_types.VXLIGHT_TYPE.VX_LIGHTPOINT
+    cDefaultColor: typing.ClassVar[UTIL_virtools_types.VxColor] = UTIL_virtools_types.VxColor(1.0, 1.0, 1.0, 1.0)
+
+    cDefaultConstantAttenuation: typing.ClassVar[float] = 1.0
+    cDefaultLinearAttenuation: typing.ClassVar[float] = 0.0
+    cDefaultQuadraticAttenuation: typing.ClassVar[float] = 0.0
+
+    cDefaultRange: typing.ClassVar[float] = 100.0
+
+    cDefaultHotSpot: typing.ClassVar[float] = math.radians(40)
+    cDefaultFalloff: typing.ClassVar[float] = math.radians(45)
+    cDefaultFalloffShape: typing.ClassVar[float] = 1.0
+
+    def __init__(self, **kwargs):
+        # assign default value for each component
+        self.mType = kwargs.get('mType', RawVirtoolsLight.cDefaultType)
+        self.mColor = kwargs.get('mColor', RawVirtoolsLight.cDefaultColor).clone()
+
+        self.mConstantAttenuation = kwargs.get('mConstantAttenuation', RawVirtoolsLight.cDefaultConstantAttenuation)
+        self.mLinearAttenuation = kwargs.get('mLinearAttenuation', RawVirtoolsLight.cDefaultLinearAttenuation)
+        self.mQuadraticAttenuation = kwargs.get('mQuadraticAttenuation', RawVirtoolsLight.cDefaultQuadraticAttenuation)
+        
+        self.mRange = kwargs.get('mRange', RawVirtoolsLight.cDefaultRange)
+
+        self.mHotSpot = kwargs.get('mHotSpot', RawVirtoolsLight.cDefaultHotSpot)
+        self.mFalloff = kwargs.get('mFalloff', RawVirtoolsLight.cDefaultFalloff)
+        self.mFalloffShape = kwargs.get('mFalloffShape', RawVirtoolsLight.cDefaultFalloffShape)
+
+    def regulate(self) -> None:
+        # regulate color and reset its alpha value
+        self.mColor.regulate()
+        self.mColor.a = 1.0
+        # regulate range
+        self.mRange = UTIL_functions.clamp_float(self.mRange, 0.0, 200.0)
+
+        # regulate attenuation
+        self.mConstantAttenuation = UTIL_functions.clamp_float(self.mConstantAttenuation, 0.0, 10.0)
+        self.mLinearAttenuation = UTIL_functions.clamp_float(self.mLinearAttenuation, 0.0, 10.0)
+        self.mQuadraticAttenuation = UTIL_functions.clamp_float(self.mQuadraticAttenuation, 0.0, 10.0)
+
+        # regulate spot cone
+        self.mHotSpot = UTIL_functions.clamp_float(self.mHotSpot, 0.0, math.radians(180))
+        self.mFalloff = UTIL_functions.clamp_float(self.mFalloff, 0.0, math.radians(180))
+        self.mFalloffShape = UTIL_functions.clamp_float(self.mFalloffShape, 0.0, 10.0)
+        # regulate spot cone size order
+        if self.mFalloff < self.mHotSpot:
+            self.mFalloff = self.mHotSpot
+
+# Blender Property Group
+
+_g_Helper_VXLIGHT_TYPE: UTIL_virtools_types.EnumPropHelper = UTIL_virtools_types.EnumPropHelper(UTIL_virtools_types.VXLIGHT_TYPE)
+
+class BBP_PG_virtools_light(bpy.types.PropertyGroup):
+    light_type: bpy.props.EnumProperty(
+        name = "Type",
+        description = "The type of this light",
+        items = _g_Helper_VXLIGHT_TYPE.generate_items(),
+        default = _g_Helper_VXLIGHT_TYPE.to_selection(RawVirtoolsLight.cDefaultType),
+        translation_context = 'BBP_PG_virtools_light/property'
+    ) # type: ignore
+
+    light_color: bpy.props.FloatVectorProperty(
+        name = "Color",
+        description = "Defines the red, green and blue components of the light.",
+        subtype = 'COLOR',
+        min = 0.0,
+        max = 1.0,
+        size = 3,
+        default = RawVirtoolsLight.cDefaultColor.to_const_rgb(),
+        translation_context = 'BBP_PG_virtools_light/property'
+    ) # type: ignore
+
+    constant_attenuation: bpy.props.FloatProperty(
+        name = "Constant Attenuation",
+        description = "Defines the constant attenuation factor.",
+        min = 0.0,
+        max = 10.0,
+        step = 10,
+        default = RawVirtoolsLight.cDefaultConstantAttenuation,
+        translation_context = 'BBP_PG_virtools_light/property'
+    ) # type: ignore
+
+    linear_attenuation: bpy.props.FloatProperty(
+        name = "Linear Attenuation",
+        description = "Defines the linear attenuation factor.",
+        min = 0.0,
+        max = 10.0,
+        step = 10,
+        default = RawVirtoolsLight.cDefaultLinearAttenuation,
+        translation_context = 'BBP_PG_virtools_light/property'
+    ) # type: ignore
+
+    quadratic_attenuation: bpy.props.FloatProperty(
+        name = "Quadratic Attenuation",
+        description = "Defines the quadratic attenuation factor.",
+        min = 0.0,
+        max = 10.0,
+        step = 10,
+        default = RawVirtoolsLight.cDefaultQuadraticAttenuation,
+        translation_context = 'BBP_PG_virtools_light/property'
+    ) # type: ignore
+
+    light_range: bpy.props.FloatProperty(
+        name = "Range",
+        description = "Defines the radius of the lighting area.",
+        min = 0.0,
+        max = 200.0,
+        step = 100,
+        default = RawVirtoolsLight.cDefaultRange,
+        translation_context = 'BBP_PG_virtools_light/property'
+    ) # type: ignore
+
+    hot_spot: bpy.props.FloatProperty(
+        name = "Hot Spot",
+        description = "Sets the value of the hot spot of the light.",
+        min = 0.0,
+        max = math.radians(180),
+        subtype = 'ANGLE',
+        default = RawVirtoolsLight.cDefaultHotSpot,
+        translation_context = 'BBP_PG_virtools_light/property'
+    ) # type: ignore
+
+    falloff: bpy.props.FloatProperty(
+        name = "Fall Off",
+        description = "Sets the light fall off rate.",
+        min = 0.0,
+        max = math.radians(180),
+        subtype = 'ANGLE',
+        default = RawVirtoolsLight.cDefaultFalloff,
+        translation_context = 'BBP_PG_virtools_light/property'
+    ) # type: ignore
+
+    falloff_shape: bpy.props.FloatProperty(
+        name = "Fall Off Shape",
+        description = "Sets the value of the light fall off shape.",
+        min = 0.0,
+        max = 10.0,
+        step = 10,
+        default = RawVirtoolsLight.cDefaultFalloffShape,
+        translation_context = 'BBP_PG_virtools_light/property'
+    ) # type: ignore
+
+# Getter Setter and Applyer
+
+def get_virtools_light(lit: bpy.types.Light) -> BBP_PG_virtools_light:
+    return lit.virtools_light
+
+def get_raw_virtools_light(lit: bpy.types.Light) -> RawVirtoolsLight:
+    props: BBP_PG_virtools_light = get_virtools_light(lit)
+    rawdata: RawVirtoolsLight = RawVirtoolsLight()
+
+    rawdata.mType = _g_Helper_VXLIGHT_TYPE.get_selection(props.light_type)
+    rawdata.mColor.from_const_rgb(props.light_color)
+
+    rawdata.mConstantAttenuation = props.constant_attenuation
+    rawdata.mLinearAttenuation = props.linear_attenuation
+    rawdata.mQuadraticAttenuation = props.quadratic_attenuation
+
+    rawdata.mRange = props.light_range
+
+    rawdata.mHotSpot = props.hot_spot
+    rawdata.mFalloff = props.falloff
+    rawdata.mFalloffShape = props.falloff_shape
+
+    rawdata.regulate()
+    return rawdata
+
+def set_raw_virtools_light(lit: bpy.types.Light, rawdata: RawVirtoolsLight) -> None:
+    props: BBP_PG_virtools_light = get_virtools_light(lit)
+
+    props.light_type = _g_Helper_VXLIGHT_TYPE.to_selection(rawdata.mType)
+    props.light_color = rawdata.mColor.to_const_rgb()
+
+    props.constant_attenuation = rawdata.mConstantAttenuation
+    props.linear_attenuation = rawdata.mLinearAttenuation
+    props.quadratic_attenuation = rawdata.mQuadraticAttenuation
+
+    props.light_range = rawdata.mRange
+
+    props.hot_spot = rawdata.mHotSpot
+    props.falloff = rawdata.mFalloff
+    props.falloff_shape = rawdata.mFalloffShape
+
+def apply_to_blender_light(lit: bpy.types.Light) -> None:
+    # get raw data first
+    rawdata: RawVirtoolsLight = get_raw_virtools_light(lit)
+
+    # set light type and color
+    match(rawdata.mType):
+        case UTIL_virtools_types.VXLIGHT_TYPE.VX_LIGHTPOINT:
+            lit.type = 'POINT'
+        case UTIL_virtools_types.VXLIGHT_TYPE.VX_LIGHTSPOT:
+            lit.type = 'SPOT'
+        case UTIL_virtools_types.VXLIGHT_TYPE.VX_LIGHTDIREC:
+            lit.type = 'SUN'
+    lit.color = rawdata.mColor.to_const_rgb()
+
+    # MARK:
+    # After set light type, we must re-fetch light object,
+    # because it seems that the object hold by this variable 
+    # is not the object after light type changes.
+    # 
+    # If I do not do this, function will throw exception 
+    # like `'PointLight' object has no attribute 'spot_size'`.
+    lit = bpy.data.lights[lit.name]
+    match(rawdata.mType):
+        case UTIL_virtools_types.VXLIGHT_TYPE.VX_LIGHTPOINT:
+            point_lit: bpy.types.PointLight = typing.cast(bpy.types.PointLight, lit)
+            point_lit.shadow_soft_size = rawdata.mRange
+        case UTIL_virtools_types.VXLIGHT_TYPE.VX_LIGHTSPOT:
+            spot_lit: bpy.types.SpotLight = typing.cast(bpy.types.SpotLight, lit)
+            spot_lit.shadow_soft_size = rawdata.mRange
+            spot_lit.spot_size = rawdata.mFalloff
+            if rawdata.mFalloff == 0: spot_lit.spot_blend = 0.0
+            else: spot_lit.spot_blend = 1.0 - rawdata.mHotSpot / rawdata.mFalloff
+        case UTIL_virtools_types.VXLIGHT_TYPE.VX_LIGHTDIREC:
+            pass
+
+# Operators
+
+class BBP_OT_apply_virtools_light(bpy.types.Operator):
+    """Apply Virtools Light to Blender Light."""
+    bl_idname = "bbp.apply_virtools_light"
+    bl_label = "Apply to Blender Light"
+    bl_options = {'UNDO'}
+    bl_translation_context = 'BBP_OT_apply_virtools_light'
+
+    @classmethod
+    def poll(cls, context):
+        return context.light is not None
+
+    def execute(self, context):
+        lit: bpy.types.Light = context.light
+        apply_to_blender_light(lit)
+        return {'FINISHED'}
+
+# Display Panel
+
+class BBP_PT_virtools_light(bpy.types.Panel):
+    """Show Virtools Light Properties"""
+    bl_label = "Virtools Light"
+    bl_idname = "BBP_PT_virtools_light"
+    bl_space_type = 'PROPERTIES'
+    bl_region_type = 'WINDOW'
+    bl_context = "data" # idk why blender use `data` as the light tab same as mesh.
+    bl_translation_context = 'BBP_PT_virtools_light'
+
+    @classmethod
+    def poll(cls, context):
+        return context.light is not None
+
+    def draw(self, context):
+        # get layout and target
+        layout = self.layout
+        layout.use_property_split = True
+        lit: bpy.types.Light = context.light
+        props: BBP_PG_virtools_light = get_virtools_light(lit)
+        rawdata: RawVirtoolsLight = get_raw_virtools_light(lit)
+
+        # draw operator
+        layout.operator(
+            BBP_OT_apply_virtools_light.bl_idname, text='Apply', icon='NODETREE',
+            text_ctxt='BBP_PT_virtools_light/draw')
+
+        # draw data
+        layout.separator()
+        layout.label(text='Basics', text_ctxt='BBP_PT_virtools_light/draw')
+        # all lights has type and color property
+        sublayout = layout.row()
+        sublayout.use_property_split = False
+        sublayout.prop(props, 'light_type', expand = True)
+        layout.prop(props, 'light_color')
+        # all light has range property exception directional light
+        if rawdata.mType != UTIL_virtools_types.VXLIGHT_TYPE.VX_LIGHTDIREC:
+            layout.prop(props, 'light_range')
+
+        # all light has attenuation exception directional light
+        if rawdata.mType != UTIL_virtools_types.VXLIGHT_TYPE.VX_LIGHTDIREC:
+            layout.separator()
+            layout.label(text='Attenuation', text_ctxt='BBP_PT_virtools_light/draw')
+            layout.prop(props, 'constant_attenuation', text='Constant', text_ctxt='BBP_PT_virtools_light/draw')
+            layout.prop(props, 'linear_attenuation', text='Linear', text_ctxt='BBP_PT_virtools_light/draw')
+            layout.prop(props, 'quadratic_attenuation', text='Quadratic', text_ctxt='BBP_PT_virtools_light/draw')
+
+        # only spot light has spot cone properties.
+        if rawdata.mType == UTIL_virtools_types.VXLIGHT_TYPE.VX_LIGHTSPOT:
+            layout.separator()
+            layout.label(text='Spot Cone', text_ctxt='BBP_PT_virtools_light/draw')
+            layout.prop(props, 'hot_spot')
+            layout.prop(props, 'falloff')
+            layout.prop(props, 'falloff_shape')
+
+# Register
+
+def register() -> None:
+    bpy.utils.register_class(BBP_PG_virtools_light)
+    bpy.utils.register_class(BBP_OT_apply_virtools_light)
+    bpy.utils.register_class(BBP_PT_virtools_light)
+
+    # add into light metadata
+    bpy.types.Light.virtools_light = bpy.props.PointerProperty(type = BBP_PG_virtools_light)
+
+def unregister() -> None:
+    # remove from metadata
+    del bpy.types.Light.virtools_light
+
+    bpy.utils.unregister_class(BBP_PT_virtools_light)
+    bpy.utils.unregister_class(BBP_OT_apply_virtools_light)
+    bpy.utils.unregister_class(BBP_PG_virtools_light)

bbp_ng/PROP_virtools_mesh.py

@@ -0,0 +1,87 @@
+import bpy
+import typing, enum
+from . import UTIL_functions, UTIL_virtools_types
+
+# Raw Data
+
+class RawVirtoolsMesh():
+    # Instance Member Declarations
+    mLitMode: UTIL_virtools_types.VXMESH_LITMODE
+    # Default Value Declarations
+    cDefaultLitMode: typing.ClassVar[UTIL_virtools_types.VXMESH_LITMODE] = UTIL_virtools_types.VXMESH_LITMODE.VX_LITMESH
+
+    def __init__(self, **kwargs):
+        # assign default value for each component
+        self.mLitMode = kwargs.get('mLitMode', RawVirtoolsMesh.cDefaultLitMode)
+
+# blender enum prop helper defines
+_g_Helper_VXMESH_LITMODE: UTIL_virtools_types.EnumPropHelper = UTIL_virtools_types.EnumPropHelper(UTIL_virtools_types.VXMESH_LITMODE)
+
+# Blender Property Group
+
+class BBP_PG_virtools_mesh(bpy.types.PropertyGroup):
+    lit_mode: bpy.props.EnumProperty(
+        name = "Lit Mode",
+        description = "Lighting mode of the mesh.",
+        items = _g_Helper_VXMESH_LITMODE.generate_items(),
+        default = _g_Helper_VXMESH_LITMODE.to_selection(RawVirtoolsMesh.cDefaultLitMode),
+        translation_context = 'BBP_PG_virtools_mesh/property'
+    ) # type: ignore
+    
+# Getter Setter
+
+def get_virtools_mesh(mesh: bpy.types.Mesh) -> BBP_PG_virtools_mesh:
+    return mesh.virtools_mesh
+
+def get_raw_virtools_mesh(mesh: bpy.types.Mesh) -> RawVirtoolsMesh:
+    props: BBP_PG_virtools_mesh = get_virtools_mesh(mesh)
+    rawdata: RawVirtoolsMesh = RawVirtoolsMesh()
+
+    rawdata.mLitMode = _g_Helper_VXMESH_LITMODE.get_selection(props.lit_mode)
+
+    return rawdata
+
+def set_raw_virtools_mesh(mesh: bpy.types.Mesh, rawdata: RawVirtoolsMesh) -> None:
+    props: BBP_PG_virtools_mesh = get_virtools_mesh(mesh)
+
+    props.lit_mode = _g_Helper_VXMESH_LITMODE.to_selection(rawdata.mLitMode)
+
+# Display Panel
+
+class BBP_PT_virtools_mesh(bpy.types.Panel):
+    """Show Virtools Mesh Properties."""
+    bl_label = "Virtools Mesh"
+    bl_idname = "BBP_PT_virtools_mesh"
+    bl_space_type = 'PROPERTIES'
+    bl_region_type = 'WINDOW'
+    bl_context = "data" # idk why blender use `data` as the mesh tab.
+    bl_translation_context = 'BBP_PT_virtools_mesh'
+    
+    @classmethod
+    def poll(cls, context):
+        return context.mesh is not None
+    
+    def draw(self, context):
+        # get layout and target
+        layout = self.layout
+        props: BBP_PG_virtools_mesh = get_virtools_mesh(context.mesh)
+
+        # draw data
+        layout.prop(props, 'lit_mode')
+
+# Register
+
+def register() -> None:
+    bpy.utils.register_class(BBP_PG_virtools_mesh)
+    bpy.utils.register_class(BBP_PT_virtools_mesh)
+
+    # add into mesh metadata
+    bpy.types.Mesh.virtools_mesh = bpy.props.PointerProperty(type = BBP_PG_virtools_mesh)
+
+def unregister() -> None:
+    # remove from metadata
+    del bpy.types.Mesh.virtools_mesh
+
+    bpy.utils.unregister_class(BBP_PT_virtools_mesh)
+    bpy.utils.unregister_class(BBP_PG_virtools_mesh)
+

bbp_ng/PROP_virtools_texture.py

@@ -0,0 +1,207 @@
+import bpy
+import typing
+from . import UTIL_virtools_types, UTIL_functions
+
+class RawVirtoolsTexture():
+    
+    # Instance Member Declarations
+    
+    mSaveOptions: UTIL_virtools_types.CK_TEXTURE_SAVEOPTIONS
+    mVideoFormat: UTIL_virtools_types.VX_PIXELFORMAT
+
+    # Default Value Declarations
+    
+    cDefaultSaveOptions: typing.ClassVar[UTIL_virtools_types.CK_TEXTURE_SAVEOPTIONS] = UTIL_virtools_types.CK_TEXTURE_SAVEOPTIONS.CKTEXTURE_RAWDATA
+    cDefaultVideoFormat: typing.ClassVar[UTIL_virtools_types.VX_PIXELFORMAT] = UTIL_virtools_types.VX_PIXELFORMAT._16_ARGB1555
+
+    def __init__(self, **kwargs):
+        # assign default value for each component
+        self.mSaveOptions = kwargs.get('mSaveOptions', RawVirtoolsTexture.cDefaultSaveOptions)
+        self.mVideoFormat = kwargs.get('mVideoFormat', RawVirtoolsTexture.cDefaultVideoFormat)
+    
+# blender enum prop helper defines
+_g_Helper_CK_TEXTURE_SAVEOPTIONS: UTIL_virtools_types.EnumPropHelper = UTIL_virtools_types.EnumPropHelper(UTIL_virtools_types.CK_TEXTURE_SAVEOPTIONS)
+_g_Helper_VX_PIXELFORMAT: UTIL_virtools_types.EnumPropHelper = UTIL_virtools_types.EnumPropHelper(UTIL_virtools_types.VX_PIXELFORMAT)
+
+class BBP_PG_virtools_texture(bpy.types.PropertyGroup):
+
+    save_options: bpy.props.EnumProperty(
+        name = "Save Options",
+        description = "When saving a composition textures or sprites can be kept as reference to external files or converted to a given format and saved inside the composition file.",
+        items = _g_Helper_CK_TEXTURE_SAVEOPTIONS.generate_items(),
+        default = _g_Helper_CK_TEXTURE_SAVEOPTIONS.to_selection(RawVirtoolsTexture.cDefaultSaveOptions),
+        translation_context = 'BBP_PG_virtools_texture/property'
+    ) # type: ignore
+    
+    video_format: bpy.props.EnumProperty(
+        name = "Video Format",
+        description = "The desired surface pixel format in video memory.",
+        items = _g_Helper_VX_PIXELFORMAT.generate_items(),
+        default = _g_Helper_VX_PIXELFORMAT.to_selection(RawVirtoolsTexture.cDefaultVideoFormat),
+        translation_context = 'BBP_PG_virtools_texture/property'
+    ) # type: ignore
+    
+#region Virtools Texture Getter Setter
+
+def get_virtools_texture(img: bpy.types.Image) -> BBP_PG_virtools_texture:
+    return img.virtools_texture
+
+def get_raw_virtools_texture(img: bpy.types.Image) -> RawVirtoolsTexture:
+    props: BBP_PG_virtools_texture = get_virtools_texture(img)
+    rawdata: RawVirtoolsTexture = RawVirtoolsTexture()
+    
+    rawdata.mSaveOptions = _g_Helper_CK_TEXTURE_SAVEOPTIONS.get_selection(props.save_options)
+    rawdata.mVideoFormat = _g_Helper_VX_PIXELFORMAT.get_selection(props.video_format)
+    return rawdata
+
+def set_raw_virtools_texture(img: bpy.types.Image, rawdata: RawVirtoolsTexture) -> None:
+    props: BBP_PG_virtools_texture = get_virtools_texture(img)
+    
+    props.save_options = _g_Helper_CK_TEXTURE_SAVEOPTIONS.to_selection(rawdata.mSaveOptions)
+    props.video_format = _g_Helper_VX_PIXELFORMAT.to_selection(rawdata.mVideoFormat)
+
+#endregion
+
+#region Virtools Texture Drawer
+
+"""!
+@remark
+Because Image do not have its unique properties window
+so we only can draw virtools texture properties in other window
+we provide various function to help draw property.
+"""
+
+def draw_virtools_texture(img: bpy.types.Image, layout: bpy.types.UILayout):
+    props: BBP_PG_virtools_texture = get_virtools_texture(img)
+    
+    layout.prop(props, 'save_options')
+    layout.prop(props, 'video_format')
+
+#endregion
+
+#region Ballance Texture Preset
+
+_g_OpaqueBallanceTexturePreset: RawVirtoolsTexture = RawVirtoolsTexture(
+    mSaveOptions = UTIL_virtools_types.CK_TEXTURE_SAVEOPTIONS.CKTEXTURE_EXTERNAL,
+    mVideoFormat = UTIL_virtools_types.VX_PIXELFORMAT._16_ARGB1555,
+)
+_g_TransparentBallanceTexturePreset: RawVirtoolsTexture = RawVirtoolsTexture(
+    mSaveOptions = UTIL_virtools_types.CK_TEXTURE_SAVEOPTIONS.CKTEXTURE_EXTERNAL,
+    mVideoFormat = UTIL_virtools_types.VX_PIXELFORMAT._32_ARGB8888,
+)
+_g_NonBallanceTexturePreset: RawVirtoolsTexture = RawVirtoolsTexture(
+    mSaveOptions = UTIL_virtools_types.CK_TEXTURE_SAVEOPTIONS.CKTEXTURE_RAWDATA,
+    mVideoFormat = UTIL_virtools_types.VX_PIXELFORMAT._32_ARGB8888,
+)
+
+## The preset collection of all Ballance texture.
+#  Key is texture name and can be used as file name checking.
+#  Value is its preset which can be assigned.
+_g_BallanceTexturePresets: dict[str, RawVirtoolsTexture] = {
+    # "atari.avi": _g_TransparentBallanceTexturePreset,
+    "atari.bmp": _g_OpaqueBallanceTexturePreset,
+    "Ball_LightningSphere1.bmp": _g_OpaqueBallanceTexturePreset,
+    "Ball_LightningSphere2.bmp": _g_OpaqueBallanceTexturePreset,
+    "Ball_LightningSphere3.bmp": _g_OpaqueBallanceTexturePreset,
+    "Ball_Paper.bmp": _g_OpaqueBallanceTexturePreset,
+    "Ball_Stone.bmp": _g_OpaqueBallanceTexturePreset,
+    "Ball_Wood.bmp": _g_OpaqueBallanceTexturePreset,
+    "Brick.bmp": _g_OpaqueBallanceTexturePreset,
+    "Button01_deselect.tga": _g_TransparentBallanceTexturePreset,
+    "Button01_select.tga": _g_TransparentBallanceTexturePreset,
+    "Button01_special.tga": _g_TransparentBallanceTexturePreset,
+    "Column_beige.bmp": _g_OpaqueBallanceTexturePreset,
+    "Column_beige_fade.tga": _g_TransparentBallanceTexturePreset,
+    "Column_blue.bmp": _g_OpaqueBallanceTexturePreset,
+    "Cursor.tga": _g_TransparentBallanceTexturePreset,
+    "Dome.bmp": _g_OpaqueBallanceTexturePreset,
+    "DomeEnvironment.bmp": _g_OpaqueBallanceTexturePreset,
+    "DomeShadow.tga": _g_TransparentBallanceTexturePreset,
+    "ExtraBall.bmp": _g_OpaqueBallanceTexturePreset,
+    "ExtraParticle.bmp": _g_OpaqueBallanceTexturePreset,
+    "E_Holzbeschlag.bmp": _g_OpaqueBallanceTexturePreset,
+    "FloorGlow.bmp": _g_OpaqueBallanceTexturePreset,
+    "Floor_Side.bmp": _g_OpaqueBallanceTexturePreset,
+    "Floor_Top_Border.bmp": _g_OpaqueBallanceTexturePreset,
+    "Floor_Top_Borderless.bmp": _g_OpaqueBallanceTexturePreset,
+    "Floor_Top_Checkpoint.bmp": _g_OpaqueBallanceTexturePreset,
+    "Floor_Top_Flat.bmp": _g_OpaqueBallanceTexturePreset,
+    "Floor_Top_Profil.bmp": _g_OpaqueBallanceTexturePreset,
+    "Floor_Top_ProfilFlat.bmp": _g_OpaqueBallanceTexturePreset,
+    "Font_1.tga": _g_TransparentBallanceTexturePreset,
+    "Gravitylogo_intro.bmp": _g_OpaqueBallanceTexturePreset,
+    "HardShadow.bmp": _g_OpaqueBallanceTexturePreset,
+    "Laterne_Glas.bmp": _g_OpaqueBallanceTexturePreset,
+    "Laterne_Schatten.tga": _g_TransparentBallanceTexturePreset,
+    "Laterne_Verlauf.tga": _g_TransparentBallanceTexturePreset,
+    "Logo.bmp": _g_OpaqueBallanceTexturePreset,
+    "Metal_stained.bmp": _g_OpaqueBallanceTexturePreset,
+    "Misc_Ufo.bmp": _g_OpaqueBallanceTexturePreset,
+    "Misc_UFO_Flash.bmp": _g_OpaqueBallanceTexturePreset,
+    "Modul03_Floor.bmp": _g_OpaqueBallanceTexturePreset,
+    "Modul03_Wall.bmp": _g_OpaqueBallanceTexturePreset,
+    "Modul11_13_Wood.bmp": _g_OpaqueBallanceTexturePreset,
+    "Modul11_Wood.bmp": _g_OpaqueBallanceTexturePreset,
+    "Modul15.bmp": _g_OpaqueBallanceTexturePreset,
+    "Modul16.bmp": _g_OpaqueBallanceTexturePreset,
+    "Modul18.bmp": _g_OpaqueBallanceTexturePreset,
+    "Modul18_Gitter.tga": _g_TransparentBallanceTexturePreset,
+    "Modul30_d_Seiten.bmp": _g_OpaqueBallanceTexturePreset,
+    "Particle_Flames.bmp": _g_OpaqueBallanceTexturePreset,
+    "Particle_Smoke.bmp": _g_OpaqueBallanceTexturePreset,
+    "PE_Bal_balloons.bmp": _g_OpaqueBallanceTexturePreset,
+    "PE_Bal_platform.bmp": _g_OpaqueBallanceTexturePreset,
+    "PE_Ufo_env.bmp": _g_OpaqueBallanceTexturePreset,
+    "Pfeil.tga": _g_TransparentBallanceTexturePreset,
+    "P_Extra_Life_Oil.bmp": _g_OpaqueBallanceTexturePreset,
+    "P_Extra_Life_Particle.bmp": _g_OpaqueBallanceTexturePreset,
+    "P_Extra_Life_Shadow.bmp": _g_OpaqueBallanceTexturePreset,
+    "Rail_Environment.bmp": _g_OpaqueBallanceTexturePreset,
+    "sandsack.bmp": _g_OpaqueBallanceTexturePreset,
+    "SkyLayer.bmp": _g_OpaqueBallanceTexturePreset,
+    "Sky_Vortex.bmp": _g_OpaqueBallanceTexturePreset,
+    "Stick_Bottom.tga": _g_TransparentBallanceTexturePreset,
+    "Stick_Stripes.bmp": _g_OpaqueBallanceTexturePreset,
+    "Target.bmp": _g_OpaqueBallanceTexturePreset,
+    "Tower_Roof.bmp": _g_OpaqueBallanceTexturePreset,
+    "Trafo_Environment.bmp": _g_OpaqueBallanceTexturePreset,
+    "Trafo_FlashField.bmp": _g_OpaqueBallanceTexturePreset,
+    "Trafo_Shadow_Big.tga": _g_TransparentBallanceTexturePreset,
+    "Tut_Pfeil01.tga": _g_TransparentBallanceTexturePreset,
+    "Tut_Pfeil_Hoch.tga": _g_TransparentBallanceTexturePreset,
+    "Wolken_intro.tga": _g_TransparentBallanceTexturePreset,
+    "Wood_Metal.bmp": _g_OpaqueBallanceTexturePreset,
+    "Wood_MetalStripes.bmp": _g_OpaqueBallanceTexturePreset,
+    "Wood_Misc.bmp": _g_OpaqueBallanceTexturePreset,
+    "Wood_Nailed.bmp": _g_OpaqueBallanceTexturePreset,
+    "Wood_Old.bmp": _g_OpaqueBallanceTexturePreset,
+    "Wood_Panel.bmp": _g_OpaqueBallanceTexturePreset,
+    "Wood_Plain.bmp": _g_OpaqueBallanceTexturePreset,
+    "Wood_Plain2.bmp": _g_OpaqueBallanceTexturePreset,
+    "Wood_Raft.bmp": _g_OpaqueBallanceTexturePreset,
+}
+
+def get_ballance_texture_preset(texname: str) -> RawVirtoolsTexture:
+    try_preset: RawVirtoolsTexture | None = _g_BallanceTexturePresets.get(texname, None)
+    if try_preset is None:
+        # fallback to non-ballance one
+        try_preset = _g_NonBallanceTexturePreset
+
+    return try_preset
+
+def get_nonballance_texture_preset() -> RawVirtoolsTexture:
+    return _g_NonBallanceTexturePreset
+
+#endregion
+
+def register() -> None:
+    bpy.utils.register_class(BBP_PG_virtools_texture)
+    
+    # add into image metadata
+    bpy.types.Image.virtools_texture = bpy.props.PointerProperty(type = BBP_PG_virtools_texture)
+
+def unregister() -> None:
+    # del from image metadata
+    del bpy.types.Image.virtools_texture
+
+    bpy.utils.unregister_class(BBP_PG_virtools_texture)

bbp_ng/UTIL_ballance_texture.py

@@ -0,0 +1,335 @@
+import bpy, bpy_extras
+import typing, os
+from . import PROP_preferences
+from . import UTIL_functions
+
+## Ballance Texture Usage
+#  The aim of this module is to make sure every Ballance texture only have 1 instance in Blender as much as we can 
+#  (it mean that if user force to add multiple textures, we can not stop them)
+#  
+#  All image loading and saving operation should be operated via this module, no matter what your are loading is or is not Ballance textures.
+#  This module provide a universal way to check whether texture is a part of Ballance textures and use different strategy to load them.
+#  
+#  The loading and saving of textures frequently happend when importing or exporting, there is 2 example about them.
+#  ```
+#  # bmx loading example
+#  bmx_texture = blabla()
+#  if bmx_texture.is_external(): 
+#      tex = UTIL_ballance_texture.load_ballance_texture(bmx_texture.filename)
+#  else: 
+#      tex = UTIL_ballance_texture.load_other_texture(os.path.join(tempfolder, 'Textures', bmx_texture.filename))
+#  texture_process(tex) # process loaded texture
+#  
+#  # nmo loading example
+#  vt_texture = blabla()
+#  place_to_load = ""
+#  if vt_texture.is_raw_data(): 
+#      place_to_load = allocate_place()
+#      save_vt_raw_data_texture(vt_texture, place_to_load)
+#  if vt_texture.is_original_file() or vt_texture.is_external():
+#      place_to_load = vt_texture.filename
+#  
+#  try_filename = UTIL_ballance_texture.get_ballance_texture_filename(place_to_load)
+#  if try_filename:
+#      # load as ballance texture
+#      tex = UTIL_ballance_texture.load_ballance_texture(try_filename)
+#  else:
+#      # load as other texture
+#      tex = UTIL_ballance_texture.load_other_texture(place_to_load)
+#  texture_process(tex) # process loaded texture
+#  
+#  ```
+#  
+#  ```
+#  # bmx saving example
+#  tex: bpy.types.Image = texture_getter()
+#  try_filename = UTIL_ballance_texture.get_ballance_texture_filename(
+#      UTIL_ballance_texture.get_texture_filepath(tex))
+#  if try_filename:
+#      write_external_filename(try_filename)
+#  else:
+#      realpath = UTIL_ballance_texture.generate_other_texture_save_path(tex, tempfolder)
+#      UTIL_ballance_texture.save_other_texture(tex, realpath)
+#      write_filename(realpath)
+#  
+#  ```
+
+#region Ballance Texture Assist Functions
+
+_g_BallanceTextureFileNames: set[str] = set((
+    # "atari.avi",
+    "atari.bmp",
+    "Ball_LightningSphere1.bmp",
+    "Ball_LightningSphere2.bmp",
+    "Ball_LightningSphere3.bmp",
+    "Ball_Paper.bmp",
+    "Ball_Stone.bmp",
+    "Ball_Wood.bmp",
+    "Brick.bmp",
+    "Button01_deselect.tga",
+    "Button01_select.tga",
+    "Button01_special.tga",
+    "Column_beige.bmp",
+    "Column_beige_fade.tga",
+    "Column_blue.bmp",
+    "Cursor.tga",
+    "Dome.bmp",
+    "DomeEnvironment.bmp",
+    "DomeShadow.tga",
+    "ExtraBall.bmp",
+    "ExtraParticle.bmp",
+    "E_Holzbeschlag.bmp",
+    "FloorGlow.bmp",
+    "Floor_Side.bmp",
+    "Floor_Top_Border.bmp",
+    "Floor_Top_Borderless.bmp",
+    "Floor_Top_Checkpoint.bmp",
+    "Floor_Top_Flat.bmp",
+    "Floor_Top_Profil.bmp",
+    "Floor_Top_ProfilFlat.bmp",
+    "Font_1.tga",
+    "Gravitylogo_intro.bmp",
+    "HardShadow.bmp",
+    "Laterne_Glas.bmp",
+    "Laterne_Schatten.tga",
+    "Laterne_Verlauf.tga",
+    "Logo.bmp",
+    "Metal_stained.bmp",
+    "Misc_Ufo.bmp",
+    "Misc_UFO_Flash.bmp",
+    "Modul03_Floor.bmp",
+    "Modul03_Wall.bmp",
+    "Modul11_13_Wood.bmp",
+    "Modul11_Wood.bmp",
+    "Modul15.bmp",
+    "Modul16.bmp",
+    "Modul18.bmp",
+    "Modul18_Gitter.tga",
+    "Modul30_d_Seiten.bmp",
+    "Particle_Flames.bmp",
+    "Particle_Smoke.bmp",
+    "PE_Bal_balloons.bmp",
+    "PE_Bal_platform.bmp",
+    "PE_Ufo_env.bmp",
+    "Pfeil.tga",
+    "P_Extra_Life_Oil.bmp",
+    "P_Extra_Life_Particle.bmp",
+    "P_Extra_Life_Shadow.bmp",
+    "Rail_Environment.bmp",
+    "sandsack.bmp",
+    "SkyLayer.bmp",
+    "Sky_Vortex.bmp",
+    "Stick_Bottom.tga",
+    "Stick_Stripes.bmp",
+    "Target.bmp",
+    "Tower_Roof.bmp",
+    "Trafo_Environment.bmp",
+    "Trafo_FlashField.bmp",
+    "Trafo_Shadow_Big.tga",
+    "Tut_Pfeil01.tga",
+    "Tut_Pfeil_Hoch.tga",
+    "Wolken_intro.tga",
+    "Wood_Metal.bmp",
+    "Wood_MetalStripes.bmp",
+    "Wood_Misc.bmp",
+    "Wood_Nailed.bmp",
+    "Wood_Old.bmp",
+    "Wood_Panel.bmp",
+    "Wood_Plain.bmp",
+    "Wood_Plain2.bmp",
+    "Wood_Raft.bmp",
+))
+
+def _get_ballance_texture_folder() -> str:
+    """!
+    Get Ballance texture folder from preferences.
+
+    @exception BBPException Ballance texture folder is not set in preferences
+
+    @return The path to Ballance texture folder.
+    """
+
+    pref: PROP_preferences.RawPreferences = PROP_preferences.get_raw_preferences()
+    if not pref.has_valid_blc_tex_folder():
+        raise UTIL_functions.BBPException("No valid Ballance texture folder in preferences.")
+    
+    return pref.mBallanceTextureFolder
+
+def _is_path_equal(path1: str, path2: str) -> bool:
+    """!
+    Check whether 2 path are equal.
+
+    The checker will call os.path.normcase and os.path.normpath in series to regulate the give path.
+
+    @param path1[in] The given absolute path 1
+    @param path2[in] The given absolute path 2
+    @return True if equal.
+    """
+
+    return os.path.normpath(os.path.normcase(path1)) == os.path.normpath(os.path.normcase(path2))
+
+#endregion
+
+#region Ballance Texture Detect Functions
+
+def get_ballance_texture_filename(texpath: str) -> str | None:
+    """!
+    Return the filename part for valid Ballance texture path.
+
+    If the file name part of given path is not a entry of Ballance texture file name list, function will return None immediately.
+    Otherwise, function will check whether the given file path is really point to the Ballance texture folder.
+
+    @exception BBPException Ballance texture folder is not set in preferences
+
+    @param imgpath[in] Absolute path to texture.
+    @return File name part of given texture path if given path is a valid Ballance texture path, or None if the path not point to a valid Ballance texture.
+    """
+    
+    # check file name first
+    filename: str = os.path.basename(texpath)
+    if filename not in _g_BallanceTextureFileNames: return None
+
+    # if file name matched, check whether it located in ballance texture folder
+    probe: str = os.path.join(_get_ballance_texture_folder(), filename)
+    if not _is_path_equal(probe, texpath): return None
+
+    return filename
+
+def is_ballance_texture_filepath(texpath: str) -> bool:
+    """!
+    Check whether the given path is a valid Ballance texture.
+
+    Simply call get_ballance_texture_filename() and check whether it return string or None.
+
+    @exception BBPException Ballance texture folder is not set in preferences
+
+    @param imgpath[in] Absolute path to texture.
+    @return True if it is Ballance texture.
+    @see get_ballance_texture_filename
+    """
+    
+    return get_ballance_texture_filename(texpath) is not None
+
+def get_texture_filepath(tex: bpy.types.Image) -> str:
+    """!
+    Get the file path referenced by the given texture.
+
+    This function will try getting the referenced file path of given texture, including packed or not packed texture.
+
+    This function will try resolving the file path when given texture is packed according to the path of 
+    current opend blender file and Ballance texture folder speficied in preferences.
+
+    If resolving failed, it may return blender packed data url, for example `\\./xxx.bmp`
+
+    @exception BBPException Ballance texture folder is not set in preferences
+
+    @param tex[in] The image where the file name need to be got.
+    @return The resolved absolute file path.
+    """
+
+    # resolve image path
+    absfilepath: str = bpy_extras.io_utils.path_reference(
+        tex.filepath, bpy.data.filepath, _get_ballance_texture_folder(),
+        'ABSOLUTE', "", None, None
+    )
+
+    # return resolved path
+    return absfilepath
+    
+def is_ballance_texture(tex: bpy.types.Image) -> bool:
+    """!
+    Check whether the provided image is Ballance texture according to its referenced file path.
+
+    A simply calling combination of get_texture_filepath and is_ballance_texture_filepath
+
+    @exception BBPException Ballance texture folder is not set in preferences
+
+    @param tex[in] The texture to check.
+    @return True if it is Ballance texture.
+    @see get_texture_filepath, is_ballance_texture_filepath
+    """
+    
+    return is_ballance_texture_filepath(get_texture_filepath(tex))
+
+#endregion
+
+#region Ballance Texture Load & Save
+
+def load_ballance_texture(texname: str) -> bpy.types.Image:
+    """!
+    Load Ballance texture.
+
+    + The returned image may be redirected to a existing image according to its file path, because all Ballance textures are shared.
+    + The loaded image is saved as external. No pack will be operated because plugin assume all user have Ballance texture folder.
+
+    @exception BBPException Ballance texture folder is not set in preferences, or provided file name is invalid.
+
+    @param texname[in] the file name (not the path) of loading Ballance texture. Invalid file name will raise exception.
+    @return The loaded image.
+    """
+    
+    # check texture name
+    if texname not in _g_BallanceTextureFileNames:
+        raise UTIL_functions.BBPException("Invalid Ballance texture file name.")
+    
+    # load image
+    # check existing image in any case. because we need make sure ballance texture is unique.
+    filepath: str = os.path.join(_get_ballance_texture_folder(), texname)
+    ret: bpy.types.Image = bpy.data.images.load(filepath, check_existing = True)
+
+    return ret
+
+def load_other_texture(texname: str) -> bpy.types.Image:
+    """!
+    Load the Texture which is not a part of Ballance texture.
+
+    This function is different with load_ballance_texture(). It can be seen as the opposition of load_ballance_texture().
+    This function is used when loading the temp images created by BMX file resolving or Virtools engine. 
+    Because these temp file will be deleted after importing, this function need pack the loaded file into blender file immediately after loading.
+
+    @remark
+    + The loaded texture will be immediately packed into blender file.
+    + Loading will NOT check any loaded image according to file path.
+
+    @param texname[in] the absolute path to the loading image.
+    @return The loaded image.
+    """
+    
+    # load image first
+    # always do not check the same image.
+    ret: bpy.types.Image = bpy.data.images.load(texname, check_existing = False)
+    
+    # then immediately pack it into file.
+    ret.pack()
+    
+    return ret
+
+def generate_other_texture_save_path(tex: bpy.types.Image, file_folder: str) -> str:
+    """!
+    Generate the path to saved file.
+
+    This function first get file name from texture, then combine it with given dest file folder, 
+    and return it.
+    Frequently used with save_other_texture to create its parameter.
+
+    @param tex[in] The saving texture
+    @param filepath[in] The absolute path to the folder where the texture will be saved.
+    @return The path to saved file.
+    """
+    return os.path.join(file_folder, os.path.basename(get_texture_filepath(tex)))
+
+def save_other_texture(tex: bpy.types.Image, filepath: str) -> None:
+    """!
+    Save the texture which is not a part of Ballance texture.
+
+    This function is frequently used when exporting something.
+    Usually used to save the texture loaded by load_other_texture, because the texture loaded by load_ballance_texture do not need save.
+    This function accept textures which is packed or not packed in blender file.
+
+    @param tex[in] The saving texture
+    @param filepath[in] The absolute path to saving file.
+    """
+    # MARK: must use keyword to assign param otherwise blender will throw error.
+    tex.save(filepath = filepath)
+
+#endregion

bbp_ng/UTIL_blender_mesh.py

@@ -0,0 +1,530 @@
+import bpy, bmesh, mathutils
+import typing, array, collections
+from . import UTIL_functions, UTIL_virtools_types
+
+## Blender Mesh Usage
+#  This module create a universal mesh visitor, including MeshReader, MeshWriter and MeshUVModifier
+#  for every other possible module using.
+#  Obviously, MeshReader is served for 2 exporter, MeshWriter is served for 2 importer.
+#  MeshWriter also served for BMERevenge module and Ballance element loading.
+#  MeshUVModifier is used by Flatten UV and Rail UV.
+#
+
+#region Assist Functions
+
+class FaceVertexData():
+    mPosIdx: int
+    mNmlIdx: int
+    mUvIdx: int
+    
+    def __init__(self, pos: int = 0, nml: int = 0, uv: int = 0):
+        self.mPosIdx = pos
+        self.mNmlIdx = nml
+        self.mUvIdx = uv
+
+class FaceData():
+    ## @remark List or tuple. List is convenient for adding and removing
+    mIndices: tuple[FaceVertexData, ...] | list[FaceVertexData]
+    ## Face used material slot index
+    #  @remark If material slot is empty, or this face do not use material, set this value to 0.
+    mMtlIdx: int
+    
+    def __init__(self, indices: tuple[FaceVertexData, ...] | list[FaceVertexData] = tuple(), mtlidx: int = 0):
+        self.mIndices = indices
+        self.mMtlIdx = mtlidx
+    
+    def conv_co(self) -> None:
+        """
+        Change indice order between Virtools and Blender
+        """
+        if isinstance(self.mIndices, list):
+            self.mIndices.reverse()
+        elif isinstance(self.mIndices, tuple):
+            self.mIndices = self.mIndices[::-1]
+        else:
+            raise UTIL_functions.BBPException('invalid indices container.')
+    
+    def is_indices_legal(self) -> bool:
+        return len(self.mIndices) >= 3
+
+class MeshWriterIngredient():
+    mVertexPosition: typing.Iterator[UTIL_virtools_types.VxVector3] | None
+    mVertexNormal: typing.Iterator[UTIL_virtools_types.VxVector3] | None
+    mVertexUV: typing.Iterator[UTIL_virtools_types.VxVector2] | None
+    mFace: typing.Iterator[FaceData] | None
+    mMaterial: typing.Iterator[bpy.types.Material | None] | None
+    
+    def __init__(self):
+        self.mVertexPosition = None
+        self.mVertexNormal = None
+        self.mVertexUV = None
+        self.mFace = None
+        self.mMaterial = None
+    
+    def is_valid(self) -> bool:
+        if self.mVertexPosition is None: return False
+        if self.mVertexNormal is None: return False
+        if self.mVertexUV is None: return False
+        if self.mFace is None: return False
+        if self.mMaterial is None: return False
+        return True
+
+def _flat_vxvector3(it: typing.Iterator[UTIL_virtools_types.VxVector3]) -> typing.Iterator[float]:
+    for entry in it:
+        yield entry.x
+        yield entry.y
+        yield entry.z
+
+def _flat_vxvector2(it: typing.Iterator[UTIL_virtools_types.VxVector2]) -> typing.Iterator[float]:
+    for entry in it:
+        yield entry.x
+        yield entry.y
+
+def _flat_face_nml_index(nml_idx: array.array, nml_array: array.array) -> typing.Iterator[float]:
+    for idx in nml_idx:
+        pos: int = idx * 3
+        yield nml_array[pos]
+        yield nml_array[pos + 1]
+        yield nml_array[pos + 2]
+
+def _flat_face_uv_index(uv_idx: array.array, uv_array: array.array) -> typing.Iterator[float]:
+    for idx in uv_idx:
+        pos: int = idx * 2
+        yield uv_array[pos]
+        yield uv_array[pos + 1]
+
+def _nest_custom_split_normal(nml_array: array.array) -> typing.Iterator[UTIL_virtools_types.ConstVxVector3]:
+    # following statement create a iterator for normals array by `iter(nml_array)`
+    # then triple it, because iterator is a reference type, so 3 items of this tuple is pointed to the same iterator and share the same iteration progress.
+    # then use star macro to pass it to zip, it will cause zip receive 3 params pointing to the same iterator.
+    # now zip() will call 3 param‘s __next__() function from left to right.
+    # zip will get following iteration result because all iterator are the same one: (0, 1, 2), (3, 4, 5) and etc (number is index to corresponding value).
+    # finally, use tuple to expand it to a tuple, not a generator.
+    return tuple(zip(*(iter(nml_array), ) * 3))
+
+class TemporaryMesh():
+    """
+    Create a temporary mesh for convenient exporting.
+    When exporting mesh, we need triangulate it first.
+    We create a temporary mesh to hold the triangulated mesh result.
+    So that original object will not be affected and keep its original geometry.
+    Please note passed bpy.types.Object must be Mesh Object.
+    """
+    
+    __mBindingObject: bpy.types.Object
+    __mTempMesh: bpy.types.Mesh
+    
+    def __init__(self, binding_obj: bpy.types.Object):
+        self.__mBindingObject = binding_obj
+        self.__mTempMesh = None
+        
+        if self.__mBindingObject.data is None:
+            raise UTIL_functions.BBPException('try getting mesh from an object without mesh.')
+        self.__mTempMesh = self.__mBindingObject.to_mesh()
+    
+    def __enter__(self):
+        return self
+    
+    def __exit__(self, exc_type, exc_value, traceback):
+        self.dispose()
+    
+    def is_valid(self) -> bool:
+        if self.__mBindingObject is None: return False
+        if self.__mTempMesh is None: return False
+        return True
+    
+    def dispose(self) -> None:
+        if self.is_valid():
+            self.__mTempMesh = None
+            self.__mBindingObject.to_mesh_clear()
+            self.__mBindingObject = None
+    
+    def get_temp_mesh(self) -> bpy.types.Mesh:
+        if not self.is_valid():
+            raise UTIL_functions.BBPException('try calling invalid TemporaryMesh.')
+        return self.__mTempMesh
+
+#endregion
+
+class MeshReader():
+    """
+    The passed mesh must be created by bpy.types.Object.to_mesh() and destroyed by bpy.types.Object.to_mesh_clear().
+    Because this class must trianglate mesh. To prevent change original mesh, this operations is essential.
+    A helper class TemporaryMesh can help you do this.
+    """
+    
+    __mAssocMesh: bpy.types.Mesh ##< The binding mesh for this reader. None if this reader is invalid.
+    
+    def __init__(self, assoc_mesh: bpy.types.Mesh):
+        self.__mAssocMesh = assoc_mesh
+        
+        # triangulate temp mesh
+        if self.is_valid():
+            self.__triangulate_mesh()
+    
+    def is_valid(self) -> bool:
+        return self.__mAssocMesh is not None
+    
+    def __enter__(self):
+        return self
+    
+    def __exit__(self, exc_type, exc_value, traceback):
+        self.dispose()
+    
+    def dispose(self) -> None:
+        if self.is_valid():
+            # reset mesh
+            self.__mAssocMesh = None
+    
+    def get_vertex_position_count(self) -> int:
+        if not self.is_valid():
+            raise UTIL_functions.BBPException('try to call an invalid MeshReader.')
+        
+        return len(self.__mAssocMesh.vertices)
+    
+    def get_vertex_position(self) -> typing.Iterator[UTIL_virtools_types.VxVector3]:
+        if not self.is_valid():
+            raise UTIL_functions.BBPException('try to call an invalid MeshReader.')
+        
+        cache: UTIL_virtools_types.VxVector3 = UTIL_virtools_types.VxVector3()
+        for vec in self.__mAssocMesh.vertices:
+            cache.x = vec.co.x
+            cache.y = vec.co.y
+            cache.z = vec.co.z
+            yield cache
+    
+    def get_vertex_normal_count(self) -> int:
+        if not self.is_valid():
+            raise UTIL_functions.BBPException('try to call an invalid MeshReader.')
+        
+        # return loops count, equaling with face count * 3 in theory.
+        return len(self.__mAssocMesh.loops)
+    
+    def get_vertex_normal(self) -> typing.Iterator[UTIL_virtools_types.VxVector3]:
+        if not self.is_valid():
+            raise UTIL_functions.BBPException('try to call an invalid MeshReader.')
+        
+        cache: UTIL_virtools_types.VxVector3 = UTIL_virtools_types.VxVector3()
+        for nml in self.__mAssocMesh.corner_normals:
+            cache.x = nml.vector.x
+            cache.y = nml.vector.y
+            cache.z = nml.vector.z
+            yield cache
+    
+    def get_vertex_uv_count(self) -> int:
+        if not self.is_valid():
+            raise UTIL_functions.BBPException('try to call an invalid MeshReader.')
+        
+        if self.__mAssocMesh.uv_layers.active is None:
+            # if no uv layer, we need make a fake one
+            # return the same value with normals.
+            # it also mean create uv for each face vertex
+            return len(self.__mAssocMesh.loops)
+        else:
+            # otherwise return its size, also equaling with face count * 3 in theory
+            return len(self.__mAssocMesh.uv_layers.active.uv)
+    
+    def get_vertex_uv(self) -> typing.Iterator[UTIL_virtools_types.VxVector2]:
+        if not self.is_valid():
+            raise UTIL_functions.BBPException('try to call an invalid MeshReader.')
+        
+        cache: UTIL_virtools_types.VxVector2 = UTIL_virtools_types.VxVector2()
+        if self.__mAssocMesh.uv_layers.active is None:
+            # create a fake one
+            cache.x = 0.0
+            cache.y = 0.0
+            for _ in range(self.get_vertex_uv_count()):
+                yield cache
+        else:
+            for uv in self.__mAssocMesh.uv_layers.active.uv:
+                cache.x = uv.vector.x
+                cache.y = uv.vector.y
+                yield cache
+    
+    def get_material_slot_count(self) -> int:
+        if not self.is_valid():
+            raise UTIL_functions.BBPException('try to call an invalid MeshReader.')
+        
+        return len(self.__mAssocMesh.materials)
+    
+    def get_material_slot(self) -> typing.Iterator[bpy.types.Material | None]:
+        """
+        @remark This generator may return None if this slot do not link to may material.
+        """
+        if not self.is_valid():
+            raise UTIL_functions.BBPException('try to call an invalid MeshReader.')
+        
+        for mtl in self.__mAssocMesh.materials:
+            yield mtl
+    
+    def get_face_count(self) -> int:
+        if not self.is_valid():
+            raise UTIL_functions.BBPException('try to call an invalid MeshReader.')
+        
+        return len(self.__mAssocMesh.polygons)
+    
+    def get_face(self) -> typing.Iterator[FaceData]:
+        if not self.is_valid():
+            raise UTIL_functions.BBPException('try to call an invalid MeshReader.')
+        
+        # detect whether we have material
+        no_mtl: bool = self.get_material_slot_count() == 0
+        
+        # use list as indices container for convenient adding and deleting.
+        cache: FaceData = FaceData([], 0)
+        for face in self.__mAssocMesh.polygons:
+            # confirm material use
+            # a face without mtl have 2 situations. first is the whole object do not have mtl
+            # another is this face use an empty mtl slot.
+            if no_mtl:
+                cache.mMtlIdx = 0
+            else:
+                cache.mMtlIdx = face.material_index
+            
+            # resize indices
+            self.__resize_face_data_indices(cache.mIndices, face.loop_total)
+            # set indices
+            for i in range(face.loop_total):
+                cache.mIndices[i].mPosIdx = self.__mAssocMesh.loops[face.loop_start + i].vertex_index
+                cache.mIndices[i].mNmlIdx = face.loop_start + i
+                cache.mIndices[i].mUvIdx = face.loop_start + i
+            
+            # return value
+            yield cache
+    
+    def __resize_face_data_indices(self, ls: list[FaceVertexData], expected_size: int) -> None:
+        diff: int = expected_size - len(ls)
+        if diff > 0:
+            # add entry
+            for _ in range(diff):
+                ls.append(FaceVertexData())
+        elif diff < 0:
+            # remove entry
+            for _ in range(diff):
+                ls.pop()
+        else:
+            # no count diff, pass
+            pass
+    
+    def __triangulate_mesh(self) -> None:
+        bm: bmesh.types.BMesh = bmesh.new()
+        bm.from_mesh(self.__mAssocMesh)
+        bmesh.ops.triangulate(bm, faces = bm.faces)
+        bm.to_mesh(self.__mAssocMesh)
+        bm.free()
+
+class MeshWriter():
+    """
+    If face do not use material, pass 0 as its material index.
+    If face do not have UV becuase it doesn't have material, you at least create 1 UV vector, eg. (0, 0),
+    then refer it to all face uv.
+    """
+    
+    __mAssocMesh: bpy.types.Mesh ##< The binding mesh for this writer. None if this writer is invalid.
+    
+    __mVertexPos: array.array ##< Array item is float(f). Length must be an integer multiple of 3.
+    __mVertexNormal: array.array ##< Array item is float(f). Length must be an integer multiple of 3.
+    __mVertexUV: array.array ##< Array item is float(f). Length must be an integer multiple of 2.
+    
+    ## Array item is int32(L).
+    #  Length must be the sum of each items in __mFaceVertexCount.
+    #  Item is face vertex position index, based on 0, pointing to __mVertexPos (visiting need multiple it with 3 because __mVertexPos is flat struct).
+    __mFacePosIndices: array.array
+    ## Same as __mFacePosIndices, but store face vertex normal index.
+    #  Array item is int32(L). Length is equal to __mFacePosIndices
+    __mFaceNmlIndices: array.array
+    ## Same as __mFacePosIndices, but store face vertex uv index.
+    #  Array item is int32(L). Length is equal to __mFacePosIndices
+    __mFaceUvIndices: array.array
+    ## Array item is int32(L).
+    #  Length is the face count.
+    #  It indicate how much vertex need to be consumed in __mFacePosIndices, __mFaceNmlIndices and __mFaceUvIndices for one face.
+    __mFaceVertexCount: array.array
+    __mFaceMtlIdx: array.array  ##< Array item is int32(L). Length is equal to __mFaceVertexCount.
+    
+    ## Material Slot.
+    #  Each item is unique make sure by __mMtlSlotMap
+    __mMtlSlot: list[bpy.types.Material | None]
+    ## The map to make sure every item in __mMtlSlot is unique.
+    #  Key is bpy.types.Material
+    #  Value is key's index in __mMtlSlot.
+    __mMtlSlotMap: dict[bpy.types.Material | None, int]
+    
+    ## The attribute name storing temporary normals data inside mesh.
+    __cTempNormalAttrName: typing.ClassVar[str] = 'temp_custom_normals'
+
+    def __init__(self, assoc_mesh: bpy.types.Mesh):
+        self.__mAssocMesh = assoc_mesh
+        
+        self.__mVertexPos = array.array('f')
+        self.__mVertexNormal = array.array('f')
+        self.__mVertexUV = array.array('f')
+        
+        self.__mFacePosIndices = array.array('L')
+        self.__mFaceNmlIndices = array.array('L')
+        self.__mFaceUvIndices = array.array('L')
+        self.__mFaceVertexCount = array.array('L')
+        self.__mFaceMtlIdx = array.array('L')
+        
+        self.__mMtlSlot = []
+        self.__mMtlSlotMap = {}
+    
+    def is_valid(self) -> bool:
+        return self.__mAssocMesh is not None
+    
+    def __enter__(self):
+        return self
+    
+    def __exit__(self, exc_type, exc_value, traceback):
+        self.dispose()
+    
+    def dispose(self):
+        if self.is_valid():
+            # write mesh
+            self.__write_mesh()
+            # reset mesh
+            self.__mAssocMesh = None
+    
+    def add_ingredient(self, data: MeshWriterIngredient):
+        if not self.is_valid():
+            raise UTIL_functions.BBPException('try to call an invalid MeshWriter.')
+        if not data.is_valid():
+            raise UTIL_functions.BBPException('invalid mesh part data.')
+        
+        # add vertex data
+        prev_vertex_pos_count: int = len(self.__mVertexPos) // 3
+        self.__mVertexPos.extend(_flat_vxvector3(data.mVertexPosition))
+        prev_vertex_nml_count: int = len(self.__mVertexNormal) // 3
+        self.__mVertexNormal.extend(_flat_vxvector3(data.mVertexNormal))
+        prev_vertex_uv_count: int = len(self.__mVertexUV) // 2
+        self.__mVertexUV.extend(_flat_vxvector2(data.mVertexUV))
+        
+        # add material slot data and create mtl remap
+        mtl_remap: list[int] = []
+        for mtl in data.mMaterial:
+            idx: int | None = self.__mMtlSlotMap.get(mtl, None)
+            if idx is not None:
+                mtl_remap.append(idx)
+            else:
+                self.__mMtlSlotMap[mtl] = len(self.__mMtlSlot)
+                mtl_remap.append(len(self.__mMtlSlot))
+                self.__mMtlSlot.append(mtl)
+        
+        # add face data
+        for face in data.mFace:
+            # check indices count
+            if not face.is_indices_legal():
+                raise UTIL_functions.BBPException('face must have at least 3 vertex.')
+            
+            # add indices
+            for vec_index in face.mIndices:
+                self.__mFacePosIndices.append(vec_index.mPosIdx + prev_vertex_pos_count)
+                self.__mFaceNmlIndices.append(vec_index.mNmlIdx + prev_vertex_nml_count)
+                self.__mFaceUvIndices.append(vec_index.mUvIdx + prev_vertex_uv_count)
+            self.__mFaceVertexCount.append(len(face.mIndices))
+            
+            # add face mtl with remap
+            mtl_idx: int = face.mMtlIdx
+            if mtl_idx < 0 or mtl_idx >= len(mtl_remap):
+                # fall back. add 0
+                self.__mFaceMtlIdx.append(0)
+            else:
+                self.__mFaceMtlIdx.append(mtl_remap[mtl_idx])
+    
+    def __write_mesh(self):
+        # detect status
+        if not self.is_valid():
+            raise UTIL_functions.BBPException('try to call an invalid MeshWriter.')
+        # and clear mesh
+        self.__clear_mesh()
+        
+        # push material data
+        for mtl in self.__mMtlSlot:
+            self.__mAssocMesh.materials.append(mtl)
+        
+        # add corresponding count for vertex position
+        self.__mAssocMesh.vertices.add(len(self.__mVertexPos) // 3)
+        # add loops data, it is the sum count of indices
+        # we use face pos indices size to get it
+        self.__mAssocMesh.loops.add(len(self.__mFacePosIndices))
+        # set face count
+        self.__mAssocMesh.polygons.add(len(self.__mFaceVertexCount))
+        # create uv layer
+        self.__mAssocMesh.uv_layers.new(do_init = False)
+        
+        # add vertex position data
+        self.__mAssocMesh.vertices.foreach_set('co', self.__mVertexPos)
+        # add face vertex pos index data
+        self.__mAssocMesh.loops.foreach_set('vertex_index', self.__mFacePosIndices)
+        # add face vertex nml by function via mesh custom attribute
+        # NOTE: Blender 4.0 / 4.1 changed. I copy these code from FBX Importer.
+        temp_normal_attribute: bpy.types.FloatVectorAttribute
+        temp_normal_attribute = typing.cast(
+            bpy.types.FloatVectorAttribute,
+            self.__mAssocMesh.attributes.new(MeshWriter.__cTempNormalAttrName, 'FLOAT_VECTOR', 'CORNER')
+        )
+        temp_normal_attribute.data.foreach_set('vector',
+            tuple(_flat_face_nml_index(self.__mFaceNmlIndices, self.__mVertexNormal))
+        )
+        # add face vertex uv by function
+        self.__mAssocMesh.uv_layers.active.uv.foreach_set('vector',
+            tuple(_flat_face_uv_index(self.__mFaceUvIndices, self.__mVertexUV))
+        )   # NOTE: blender 3.5 changed. UV must be visited by .uv, not the .data
+        
+        # iterate face to set face data
+        f_vertex_idx: int = 0
+        for fi in range(len(self.__mFaceVertexCount)):
+            # set start loop
+            # NOTE: blender 3.6 changed. Loop setting in polygon do not need set loop_total any more.
+            # the loop_total will be auto calculated by the next loop_start.
+            # loop_total become read-only
+            self.__mAssocMesh.polygons[fi].loop_start = f_vertex_idx
+            
+            # set material index
+            self.__mAssocMesh.polygons[fi].material_index = self.__mFaceMtlIdx[fi]
+            
+            # set auto smooth. it is IMPORTANT
+            # because it related to whether custom split normal can work
+            self.__mAssocMesh.polygons[fi].use_smooth = True
+            
+            # inc vertex idx
+            f_vertex_idx += self.__mFaceVertexCount[fi]
+        
+        # validate mesh.
+        # it is IMPORTANT that do NOT delete custom data
+        # because we need use these data to set custom split normal later
+        self.__mAssocMesh.validate(clean_customdata = False)
+        # update mesh without mesh calc
+        self.__mAssocMesh.update(calc_edges = False, calc_edges_loose = False)
+        
+        # set custom split normal data
+        # this operation must copy preserved normal data from loops, not the array data in this class,
+        # because the validate() may change the mesh and if change happended, an error will occur when applying normals (not matched loops count).
+        # this should not happend in normal case, for testing, please load "Level_1.NMO" (Ballance Level 1).
+        
+        # copy data from loops preserved in validate().
+        # NOTE: Blender 4.0 / 4.1 changed. I copy these code from FBX Importer.
+        loops_normals = array.array('f', [0.0] * (len(self.__mAssocMesh.loops) * 3))
+        temp_normal_attribute = typing.cast(
+            bpy.types.FloatVectorAttribute, 
+            self.__mAssocMesh.attributes[MeshWriter.__cTempNormalAttrName]
+        )
+        temp_normal_attribute.data.foreach_get("vector", loops_normals)
+        # apply data
+        self.__mAssocMesh.normals_split_custom_set(
+            tuple(_nest_custom_split_normal(loops_normals))
+        )
+        self.__mAssocMesh.attributes.remove(
+            # MARK: idk why I need fucking get this attribute again.
+            # But if I were not, this function must raise bullshit exception!
+            self.__mAssocMesh.attributes[MeshWriter.__cTempNormalAttrName]
+        )
+
+    def __clear_mesh(self):
+        if not self.is_valid():
+            raise UTIL_functions.BBPException('try to call an invalid MeshWriter.')
+        
+        # clear geometry
+        self.__mAssocMesh.clear_geometry()
+        # clear mtl slot because clear_geometry will not do this.
+        self.__mAssocMesh.materials.clear()

bbp_ng/UTIL_bme.py

@@ -0,0 +1,557 @@
+import bpy, mathutils
+import os, json, enum, typing, math
+from . import PROP_virtools_group, PROP_bme_material
+from . import UTIL_functions, UTIL_icons_manager, UTIL_blender_mesh, UTIL_virtools_types, UTIL_naming_convension
+
+## NOTE: Outside caller should use BME struct's unique indetifier to visit each prototype
+#  and drive this class' functions to work.
+
+#region Prototype Visitor
+
+class PrototypeShowcaseCfgsTypes(enum.Enum):
+    Integer = 'int'
+    Float = 'float'
+    Boolean = 'bool'
+    Face = 'face'
+
+class PrototypeShowcaseTypes(enum.Enum):
+    No = 'none'
+    Floor = 'floor'
+    Rail = 'rail'
+    Wood = 'wood'
+
+TOKEN_IDENTIFIER: str = 'identifier'
+
+TOKEN_SHOWCASE: str = 'showcase'
+TOKEN_SHOWCASE_TITLE: str = 'title'
+TOKEN_SHOWCASE_ICON: str = 'icon'
+TOKEN_SHOWCASE_TYPE: str = 'type'
+TOKEN_SHOWCASE_CFGS: str = 'cfgs'
+TOKEN_SHOWCASE_CFGS_FIELD: str = 'field'
+TOKEN_SHOWCASE_CFGS_TYPE: str = 'type'
+TOKEN_SHOWCASE_CFGS_TITLE: str = 'title'
+TOKEN_SHOWCASE_CFGS_DESC: str = 'desc'
+TOKEN_SHOWCASE_CFGS_DEFAULT: str = 'default'
+
+TOKEN_SKIP: str = 'skip'
+
+TOKEN_PARAMS: str = 'params'
+TOKEN_PARAMS_FIELD: str = 'field'
+TOKEN_PARAMS_DATA: str = 'data'
+
+TOKEN_VARS: str = 'vars'
+TOKEN_VARS_FIELD: str = 'field'
+TOKEN_VARS_DATA: str = 'data'
+
+TOKEN_VERTICES: str = 'vertices'
+TOKEN_VERTICES_SKIP: str = 'skip'
+TOKEN_VERTICES_DATA: str = 'data'
+
+TOKEN_FACES: str = 'faces'
+TOKEN_FACES_SKIP: str = 'skip'
+TOKEN_FACES_TEXTURE: str = 'texture'
+TOKEN_FACES_INDICES: str = 'indices'
+TOKEN_FACES_UVS: str = 'uvs'
+TOKEN_FACES_NORMALS: str = 'normals'
+
+TOKEN_INSTANCES: str = 'instances'
+TOKEN_INSTANCES_IDENTIFIER: str = 'identifier'
+TOKEN_INSTANCES_SKIP: str = 'skip'
+TOKEN_INSTANCES_PARAMS: str = 'params'
+TOKEN_INSTANCES_TRANSFORM: str = 'transform'
+
+#endregion
+
+#region Prototype Loader
+
+## The list storing BME prototype.
+_g_BMEPrototypes: list[dict[str, typing.Any]] = []
+## The dict. Key is prototype identifier. value is the index of prototype in prototype list.
+_g_BMEPrototypeIndexMap: dict[str, int] = {}
+
+# the core loader
+for walk_root, walk_dirs, walk_files in os.walk(os.path.join(os.path.dirname(__file__), 'jsons')):
+    for relfile in walk_files:
+        if not relfile.endswith('.json'): continue
+        with open(os.path.join(walk_root, relfile), 'r', encoding = 'utf-8') as fp:
+            proto: dict[str, typing.Any]
+            for proto in json.load(fp):
+                # insert index to map
+                _g_BMEPrototypeIndexMap[proto[TOKEN_IDENTIFIER]] = len(_g_BMEPrototypes)
+                # add into list
+                _g_BMEPrototypes.append(proto)
+
+def _get_prototype_by_identifier(ident: str) -> dict[str, typing.Any]:
+    return _g_BMEPrototypes[_g_BMEPrototypeIndexMap[ident]]
+
+#endregion
+
+#region Programmable Field Calc
+
+def _env_fct_distance(x1: float, y1: float, x2: float, y2: float) -> float:
+    diff = mathutils.Vector((x2, y2)) - mathutils.Vector((x1, y1))
+    return diff.length
+
+def _env_fct_angle(x1: float, y1: float, x2: float, y2: float) -> float:
+    # compute blender angle first
+    # computed blender angle has some issues:
+    # first, it is range from -180 to 180 (0 is +X axis).
+    # second, its direction (clockwise is positive) is opposite with blender rotation direction (counter-clockwise is positive).
+    diff = mathutils.Vector((x2, y2)) - mathutils.Vector((x1, y1))
+    bld_angle = math.degrees(mathutils.Vector((1,0)).angle_signed(diff, 0))
+
+    # flip it first
+    bld_angle = -bld_angle
+    # process positove number and negative number respectively
+    # to let it range change from -180~180 to 0~360
+    if bld_angle > 0: return bld_angle
+    else: return 360 + bld_angle
+
+_g_ProgFieldGlobals: dict[str, typing.Any] = {
+    # constant
+    'pi': math.pi,
+    'tau': math.tau,
+    
+    # math functions
+    'sin': math.sin,
+    'cos': math.cos,
+    'tan': math.tan,
+    'asin': math.asin,
+    'acos': math.acos,
+    'atan': math.atan,
+    
+    'pow': math.pow,
+    'sqrt': math.sqrt,
+    
+    'fabs': math.fabs,
+    
+    'degrees': math.degrees,
+    'radians': math.radians,
+    
+    # builtin functions
+    'abs': abs,
+    
+    'int': int,
+    'float': float,
+    'str': str,
+    'bool': bool,
+    
+    # my custom matrix functions
+    'move': lambda x, y, z: mathutils.Matrix.Translation((x, y, z)),
+    'rot': lambda x, y, z: mathutils.Matrix.LocRotScale(None, mathutils.Euler((math.radians(x), math.radians(y), math.radians(z)), 'XYZ'), None),
+    'scale': lambda x, y, z: mathutils.Matrix.LocRotScale(None, None, (x, y, z)),
+    'ident': lambda: mathutils.Matrix.Identity(4),
+
+    # my misc custom functions
+    'distance': _env_fct_distance,
+    'angle': _env_fct_angle,
+}
+
+def _eval_showcase_cfgs_default(strl: str) -> typing.Any:
+    return eval(strl, _g_ProgFieldGlobals, None)
+
+def _eval_params(strl: str, cfgs_data: dict[str, typing.Any]) -> typing.Any:
+    return eval(strl, _g_ProgFieldGlobals, cfgs_data)
+
+def _eval_skip(strl: str, params_data: dict[str, typing.Any]) -> typing.Any:
+    return eval(strl, _g_ProgFieldGlobals, params_data)
+
+def _eval_vars(strl: str, params_data: dict[str, typing.Any]) -> typing.Any:
+    return eval(strl, _g_ProgFieldGlobals, params_data)
+
+def _eval_others(strl: str, params_vars_data: dict[str, typing.Any]) -> typing.Any:
+    return eval(strl, _g_ProgFieldGlobals, params_vars_data)
+
+#endregion
+
+#region Prototype Helper
+
+class PrototypeShowcaseCfgDescriptor():
+    __mRawCfg:  dict[str, str]
+    
+    def __init__(self, raw_cfg: dict[str, str]):
+        self.__mRawCfg = raw_cfg
+    
+    def get_field(self) -> str:
+        return self.__mRawCfg[TOKEN_SHOWCASE_CFGS_FIELD]
+    
+    def get_type(self) -> PrototypeShowcaseCfgsTypes:
+        return PrototypeShowcaseCfgsTypes(self.__mRawCfg[TOKEN_SHOWCASE_CFGS_TYPE])
+    
+    def get_title(self) -> str:
+        return self.__mRawCfg[TOKEN_SHOWCASE_CFGS_TITLE]
+    
+    def get_desc(self) -> str:
+        return self.__mRawCfg[TOKEN_SHOWCASE_CFGS_DESC]
+    
+    def get_default(self) -> typing.Any:
+        return _eval_showcase_cfgs_default(self.__mRawCfg[TOKEN_SHOWCASE_CFGS_DEFAULT])
+
+class EnumPropHelper(UTIL_functions.EnumPropHelper):
+    """
+    The BME specialized Blender EnumProperty helper.
+    """
+    
+    def __init__(self):
+        # init parent class
+        UTIL_functions.EnumPropHelper.__init__(
+            self,
+            self.get_bme_identifiers(),
+            lambda x: x,
+            lambda x: x,
+            lambda x: self.get_bme_showcase_title(x),
+            lambda _: '',
+            lambda x: self.get_bme_showcase_icon(x)
+        )
+    
+    def get_bme_identifiers(self) -> tuple[str, ...]:
+        """
+        Get the identifier of prototype which need to be exposed to user.
+        Template prototype is not included.
+        """
+        return tuple(
+            x[TOKEN_IDENTIFIER] # get identifier
+            for x in filter(lambda x: x[TOKEN_SHOWCASE] is not None, _g_BMEPrototypes)  # filter() to filter no showcase template.
+        )
+    
+    def get_bme_showcase_title(self, ident: str) -> str:
+        """
+        Get BME display title by prototype identifier.
+        """
+        # get prototype first
+        proto: dict[str, typing.Any] = _get_prototype_by_identifier(ident)
+        # visit title field
+        return proto[TOKEN_SHOWCASE][TOKEN_SHOWCASE_TITLE]
+    
+    def get_bme_showcase_icon(self, ident: str) -> int:
+        """
+        Get BME icon by prototype's identifier
+        """
+        # get prototype specified icon name
+        proto: dict[str, typing.Any] = _get_prototype_by_identifier(ident)
+        icon_name: str = proto[TOKEN_SHOWCASE][TOKEN_SHOWCASE_ICON]
+        # get icon from icon manager
+        cache: int | None = UTIL_icons_manager.get_bme_icon(icon_name)
+        if cache is None: return UTIL_icons_manager.get_empty_icon()
+        else: return cache
+    
+    def get_bme_showcase_cfgs(self, ident: str) -> typing.Iterator[PrototypeShowcaseCfgDescriptor]:
+        # get prototype first
+        proto: dict[str, typing.Any] = _get_prototype_by_identifier(ident)
+        # use map to batch create descriptor
+        return map(lambda x: PrototypeShowcaseCfgDescriptor(x), proto[TOKEN_SHOWCASE][TOKEN_SHOWCASE_CFGS])
+
+#endregion
+
+#region Core Creator
+
+def create_bme_struct_wrapper(ident: str, cfgs: dict[str, typing.Any]) -> bpy.types.Object:
+    # get prototype first
+    proto: dict[str, typing.Any] = _get_prototype_by_identifier(ident)
+    
+    # analyse params by given cfgs
+    params: dict[str, typing.Any] = {}
+    for proto_param in proto[TOKEN_PARAMS]:
+        params[proto_param[TOKEN_PARAMS_FIELD]] = _eval_params(proto_param[TOKEN_PARAMS_DATA], cfgs)
+    
+    # create used mesh
+    mesh: bpy.types.Mesh = bpy.data.meshes.new('BMEStruct')
+    
+    # create mesh writer and bme mtl helper
+    # recursively calling underlying creation function
+    with UTIL_blender_mesh.MeshWriter(mesh) as writer:
+        with PROP_bme_material.BMEMaterialsHelper(bpy.context.scene) as bmemtl:
+            create_bme_struct(
+                ident,
+                writer,
+                bmemtl,
+                mathutils.Matrix.Identity(4),
+                params
+            )
+    
+    # create object and assign prop
+    # get obj info first
+    obj_info: UTIL_naming_convension.BallanceObjectInfo
+    match(PrototypeShowcaseTypes(proto[TOKEN_SHOWCASE][TOKEN_SHOWCASE_TYPE])):
+        case PrototypeShowcaseTypes.No:
+            obj_info = UTIL_naming_convension.BallanceObjectInfo.create_from_others(UTIL_naming_convension.BallanceObjectType.DECORATION)
+        case PrototypeShowcaseTypes.Floor:
+            obj_info = UTIL_naming_convension.BallanceObjectInfo.create_from_others(UTIL_naming_convension.BallanceObjectType.FLOOR)
+        case PrototypeShowcaseTypes.Rail:
+            obj_info = UTIL_naming_convension.BallanceObjectInfo.create_from_others(UTIL_naming_convension.BallanceObjectType.RAIL)
+        case PrototypeShowcaseTypes.Wood:
+            obj_info = UTIL_naming_convension.BallanceObjectInfo.create_from_others(UTIL_naming_convension.BallanceObjectType.WOOD)
+    # then get object name
+    obj_name: str | None = UTIL_naming_convension.YYCToolchainConvention.set_to_name(obj_info, None)
+    if obj_name is None: raise UTIL_functions.BBPException('impossible null name')
+    # create object by name
+    obj: bpy.types.Object = bpy.data.objects.new(obj_name, mesh)
+    # assign virtools groups
+    UTIL_naming_convension.VirtoolsGroupConvention.set_to_object(obj, obj_info, None)
+    
+    # return object
+    return obj
+
+def create_bme_struct(
+        ident: str,
+        writer: UTIL_blender_mesh.MeshWriter,
+        bmemtl: PROP_bme_material.BMEMaterialsHelper,
+        transform: mathutils.Matrix,
+        params: dict[str, typing.Any]) -> None:
+    # get prototype first
+    proto: dict[str, typing.Any] = _get_prototype_by_identifier(ident)
+    
+    # check whether skip the whole struct before cal vars
+    if _eval_skip(proto[TOKEN_SKIP], params) == True:
+        return
+    
+    # calc vars by given params
+    # please note i will add entries directly into params dict
+    # but the params dict will not used independently later,
+    # all following use is the union of params and vars dict.
+    # so it is safe.
+    for proto_var in proto[TOKEN_VARS]:
+        params[proto_var[TOKEN_VARS_FIELD]] = _eval_vars(proto_var[TOKEN_VARS_DATA], params)
+    
+    # collect valid face and vertices data for following using.
+    # if NOT skip, add into valid list
+    valid_vec_idx: list[int] = []
+    for vec_idx, proto_vec in enumerate(proto[TOKEN_VERTICES]):
+        if _eval_others(proto_vec[TOKEN_VERTICES_SKIP], params) == False:
+            valid_vec_idx.append(vec_idx)
+    valid_face_idx: list[int] = []
+    for face_idx, proto_face in enumerate(proto[TOKEN_FACES]):
+        if _eval_others(proto_face[TOKEN_FACES_SKIP], params) == False:
+            valid_face_idx.append(face_idx)
+    
+    # create mtl slot remap to help following mesh adding
+    # because mesh writer do not accept string format mtl slot visiting,
+    # it only accept int based mtl slot index.
+    # 
+    # Also we build face used mtl slot index at the same time.
+    # So we do not analyse texture field again when providing face data.
+    # The result is in `prebuild_face_mtl_idx` and please note it will store all face's mtl index.
+    # For example: if face 0 is skipped and face 1 is used, the first entry in `prebuild_face_mtl_idx`
+    # will be the mtl slot index used by face 0, not 1. And its length is equal to the face count.
+    # However, because face 0 is skipped, so the entry is not used and default set to 0.
+    # 
+    # NOTE: since Python 3.6, the item of builtin dict is ordered by inserting order.
+    # we rely on this to implement following features.
+    mtl_remap: dict[str, int] = {}
+    prebuild_face_mtl_idx: list[int] = [0] * len(proto[TOKEN_FACES])
+    for face_idx in valid_face_idx:
+        # eval mtl name
+        mtl_name: str = _eval_others(proto[TOKEN_FACES][face_idx][TOKEN_FACES_TEXTURE], params)
+        # try insert into remap and record to face mtl idx
+        if mtl_name not in mtl_remap:
+            # record index
+            prebuild_face_mtl_idx[face_idx] = len(mtl_remap)
+            # add into remap if not exist
+            mtl_remap[mtl_name] = len(mtl_remap)
+        else:
+            # if existing, no need to add into remap
+            # but we need get its index from remap
+            prebuild_face_mtl_idx[face_idx] = mtl_remap.get(mtl_name, 0)
+
+    # pre-compute vertices data because we may need used later.
+    # Because if face normal data is null, it mean that we need to compute it
+    # by given vertices.
+    # The computed vertices is stored in `prebuild_vec_data` and is NOT like `prebuild_face_mtl_idx`,
+    # we only store valid one in `prebuild_vec_data`.
+    prebuild_vec_data: list[UTIL_virtools_types.ConstVxVector3 | None] = []
+    cache_bv: mathutils.Vector = mathutils.Vector((0, 0, 0))
+    for vec_idx in valid_vec_idx:
+        # but it need mul with transform matrix
+        cache_bv.x, cache_bv.y, cache_bv.z = _eval_others(proto[TOKEN_VERTICES][vec_idx][TOKEN_VERTICES_DATA], params)
+        # mul with transform matrix
+        cache_bv = typing.cast(mathutils.Vector, transform @ cache_bv)
+        # get result
+        prebuild_vec_data.append((cache_bv.x, cache_bv.y, cache_bv.z))
+
+    # Check whether given transform is mirror matrix
+    # because mirror matrix will reverse triangle indice order.
+    # If matrix is mirror matrix, we need reverse it again in following procession,
+    # including getting uv, calculating normal and providing face data.
+    mirror_matrix: bool = _is_mirror_matrix(transform)
+    
+    # prepare mesh part data
+    mesh_part: UTIL_blender_mesh.MeshWriterIngredient = UTIL_blender_mesh.MeshWriterIngredient()
+    def vpos_iterator() -> typing.Iterator[UTIL_virtools_types.VxVector3]:
+        # simply get data from prebuild vec data
+        v: UTIL_virtools_types.VxVector3 = UTIL_virtools_types.VxVector3()
+        for vec_data in prebuild_vec_data:
+            # skip skipped vertices
+            if vec_data is None: continue
+            # yield result
+            v.x, v.y, v.z = vec_data
+            yield v
+    mesh_part.mVertexPosition = vpos_iterator()
+    def vnml_iterator() -> typing.Iterator[UTIL_virtools_types.VxVector3]:
+        # prepare normal used transform first
+        # ref: https://zhuanlan.zhihu.com/p/96717729
+        nml_transform: mathutils.Matrix = transform.inverted_safe().transposed()
+        # prepare vars
+        bv: mathutils.Vector = mathutils.Vector((0, 0, 0))
+        v: UTIL_virtools_types.VxVector3 = UTIL_virtools_types.VxVector3()
+        for face_idx in valid_face_idx:
+            face_data: dict[str, typing.Any] = proto[TOKEN_FACES][face_idx]
+            face_nml_data: list[str] | None = face_data[TOKEN_FACES_NORMALS]
+            if face_nml_data is None:
+                # nml is null, we need compute by ourselves
+                # get first 3 entries in indices list as the compution ref
+                # please note that we may need reverse it
+                face_indices_data: list[int]
+                if mirror_matrix:
+                    face_indices_data = face_data[TOKEN_FACES_INDICES][::-1]
+                else:
+                    face_indices_data = face_data[TOKEN_FACES_INDICES][:]
+                # compute it by getting vertices info from prebuild vertices data
+                # because the normals is computed from transformed vertices
+                # so no need to correct its by normal transform.
+                bv.x, bv.y, bv.z = _compute_normals(
+                    typing.cast(UTIL_virtools_types.ConstVxVector3, prebuild_vec_data[face_indices_data[0]]),
+                    typing.cast(UTIL_virtools_types.ConstVxVector3, prebuild_vec_data[face_indices_data[1]]),
+                    typing.cast(UTIL_virtools_types.ConstVxVector3, prebuild_vec_data[face_indices_data[2]])
+                )
+                # yield result with N times (N = indices count)
+                v.x, v.y, v.z = bv.x, bv.y, bv.z
+                for _ in range(len(face_indices_data)):
+                    yield v
+            else:
+                # nml is given, analyse programable fields
+                for mtl_data in face_nml_data:
+                    # BME normals need transform by matrix first,
+                    bv.x, bv.y, bv.z = _eval_others(mtl_data, params)
+                    bv = typing.cast(mathutils.Vector, nml_transform @ bv)
+                    # then normalize it
+                    bv.normalize()
+                    # yield result
+                    v.x, v.y, v.z = bv.x, bv.y, bv.z
+                    yield v
+    mesh_part.mVertexNormal = vnml_iterator()
+    def vuv_iterator() -> typing.Iterator[UTIL_virtools_types.VxVector2]:
+        v: UTIL_virtools_types.VxVector2 = UTIL_virtools_types.VxVector2()
+        for face_idx in valid_face_idx:
+            face_data: dict[str, typing.Any] = proto[TOKEN_FACES][face_idx]
+            # iterate uv list considering mirror matrix
+            indices_count: int = len(face_data[TOKEN_FACES_INDICES])
+            for i in (range(indices_count)[::-1] if mirror_matrix else range(indices_count)):
+                # BME uv do not need any extra process
+                v.x, v.y = _eval_others(face_data[TOKEN_FACES_UVS][i], params)
+                yield v
+    mesh_part.mVertexUV = vuv_iterator()
+    def mtl_iterator() -> typing.Iterator[bpy.types.Material | None]:
+        for mtl_name in mtl_remap.keys():
+            yield bmemtl.get_material(mtl_name)
+    mesh_part.mMaterial = mtl_iterator()
+    def face_iterator() -> typing.Iterator[UTIL_blender_mesh.FaceData]:
+        # create face data with 3 placeholder
+        f: UTIL_blender_mesh.FaceData = UTIL_blender_mesh.FaceData(
+            [UTIL_blender_mesh.FaceVertexData() for i in range(3)]
+        )
+        
+        # create a internal counter to count how many indices has been processed
+        # this counter will be used to calc uv and normal index
+        # because these are based on face, not vertex position index.
+        face_counter: int = 0
+        
+        # iterate valid face
+        for face_idx in valid_face_idx:
+            # get face data
+            face_data: dict[str, typing.Any] = proto[TOKEN_FACES][face_idx]
+            
+            # get face indices considering the mirror matrix
+            face_indices: list[int]
+            if mirror_matrix:
+                face_indices = face_data[TOKEN_FACES_INDICES][::-1]
+            else:
+                face_indices = face_data[TOKEN_FACES_INDICES][:]
+            # calc indices count
+            indices_count: int = len(face_indices)
+            # resize face data to fulfill req
+            while len(f.mIndices) > indices_count:
+                f.mIndices.pop()
+            while len(f.mIndices) < indices_count:
+                f.mIndices.append(UTIL_blender_mesh.FaceVertexData())
+            
+            # fill the data
+            for i in range(indices_count):
+                # fill vertex position data by indices
+                f.mIndices[i].mPosIdx = face_indices[i]
+                # fill nml and uv based on face index
+                f.mIndices[i].mNmlIdx = face_counter + i
+                f.mIndices[i].mUvIdx = face_counter + i
+            
+            # add current face indices count to internal counter
+            face_counter += indices_count
+            
+            # fill texture data
+            f.mMtlIdx = prebuild_face_mtl_idx[face_idx]
+            
+            # return data once
+            yield f
+    mesh_part.mFace = face_iterator()
+    # add part to writer
+    writer.add_ingredient(mesh_part)
+    
+    # then we incursively process instance creation
+    for proto_instance in proto[TOKEN_INSTANCES]:
+        # check whether skip this instance
+        if _eval_others(proto_instance[TOKEN_INSTANCES_SKIP], params) == True:
+            continue
+        
+        # calc instance params
+        instance_params: dict[str, typing.Any] = {}
+        proto_instance_params: dict[str, str] = proto_instance[TOKEN_INSTANCES_PARAMS]
+        for proto_inst_param_field, proto_inst_param_data in proto_instance_params.items():
+            instance_params[proto_inst_param_field] = _eval_others(proto_inst_param_data, params)
+        
+        # call recursively
+        create_bme_struct(
+            proto_instance[TOKEN_INSTANCES_IDENTIFIER],
+            writer,
+            bmemtl,
+            # left-mul transform, because self transform should be applied first, the apply parent's transform
+            transform @ _eval_others(proto_instance[TOKEN_INSTANCES_TRANSFORM], params),
+            instance_params
+        )
+
+#endregion
+
+#region Creation Assist Functions
+
+def _compute_normals(
+    point1: UTIL_virtools_types.ConstVxVector3,
+    point2: UTIL_virtools_types.ConstVxVector3,
+    point3: UTIL_virtools_types.ConstVxVector3) -> UTIL_virtools_types.ConstVxVector3:
+    # build vector
+    p1: mathutils.Vector = mathutils.Vector(point1)
+    p2: mathutils.Vector = mathutils.Vector(point2)
+    p3: mathutils.Vector = mathutils.Vector(point3)
+    
+    vector1: mathutils.Vector = p2 - p1
+    vector2: mathutils.Vector = p3 - p2
+    
+    # do vector x mutiply
+    # vector1 x vector2
+    corss_mul: mathutils.Vector = vector1.cross(vector2)
+    
+    # do a normalization
+    corss_mul.normalize()
+    return (corss_mul.x, corss_mul.y, corss_mul.z)
+
+def _is_mirror_matrix(mat: mathutils.Matrix) -> bool:
+    """
+    Reflection matrix (aka. mirror matrix) is a special scaling matrix.
+    In this matrix, 1 or 3 scaling factor is minus number.
+
+    Mirror matrix will cause the inverse of triangle indice order.
+    So we need detect it and re-reverse when creating bm struct.
+    This function can detect whether given matrix is mirror matrix.
+
+    Reference: https://zhuanlan.zhihu.com/p/96717729
+    """
+    return mat.is_negative
+    #return mat.to_3x3().determinant() < 0
+
+#endregion

bbp_ng/UTIL_file_browser.py

@@ -0,0 +1,101 @@
+import bpy, bpy_extras
+
+## File Browser Usage
+#  These created file browser is just a futher wrapper of `bpy_extras.io_utils.ExportHelper`
+#  So user must use it like ExportHelper. It mean inhert it and no need to write invoke function.
+#  
+#  These wrapper also provide general visitor for getting input file name or directory:
+#  * general_get_filename()
+#  * general_get_directory()
+#  
+#  For example:
+#  ```
+#  class BBP_OT_custom_import(bpy.types.Operator, UTIL_file_browser.OpenBmxFile)
+#  
+#      def execute(self, context):
+#          print(self.general_get_filename()) # get file name if support
+#          print(self.general_get_directory()) # get file name if support
+#      
+#  ```
+
+class ImportBallanceImage(bpy_extras.io_utils.ImportHelper):
+
+    # no need to set file ext because we support multiple file ext.
+    # see ImportGLTF2 for more info.
+    # filename_ext = ".bmp"
+
+    # set with 2 file ext with ; as spelittor
+    # see ImportGLTF2 for more info.
+    filter_glob: bpy.props.StringProperty(
+        default = "*.bmp;*.tga",
+        options = {'HIDDEN'}
+    ) # type: ignore
+
+    def general_set_filename(self, filename: str) -> None:
+        self.filepath = filename
+
+    def general_get_filename(self) -> str:
+        return self.filepath
+    
+class ImportBmxFile(bpy_extras.io_utils.ImportHelper):
+
+    # set file ext filter
+    filename_ext = ".bmx"
+    filter_glob: bpy.props.StringProperty(
+        default = "*.bmx",
+        options = {'HIDDEN'}
+    ) # type: ignore
+
+    def general_get_filename(self) -> str:
+        return self.filepath
+    
+class ExportBmxFile(bpy_extras.io_utils.ExportHelper):
+
+    # set file ext filter
+    filename_ext = ".bmx"
+    filter_glob: bpy.props.StringProperty(
+        default = "*.bmx",
+        options = {'HIDDEN'}
+    ) # type: ignore
+
+    def general_get_filename(self) -> str:
+        return self.filepath
+    
+class ImportVirtoolsFile(bpy_extras.io_utils.ImportHelper):
+
+    # we support multiple file ext, set like ImportBallanceImage
+    # filename_ext = ".nmo"
+    filter_glob: bpy.props.StringProperty(
+        default = "*.nmo;*.cmo;*.vmo",
+        options = {'HIDDEN'}
+    ) # type: ignore
+
+    def general_get_filename(self) -> str:
+        return self.filepath
+    
+class ExportVirtoolsFile(bpy_extras.io_utils.ExportHelper):
+
+    # only support export nmo file
+    filename_ext = ".nmo"
+    filter_glob: bpy.props.StringProperty(
+        default = "*.nmo",
+        options = {'HIDDEN'}
+    ) # type: ignore
+
+    def general_get_filename(self) -> str:
+        return self.filepath
+    
+class ImportDirectory(bpy_extras.io_utils.ImportHelper):
+
+    # add directory prop to receive directory
+    directory: bpy.props.StringProperty() # type: ignore
+
+    # blank filter
+    filter_glob: bpy.props.StringProperty(
+        default = "",
+        options = {'HIDDEN'}
+    ) # type: ignore
+    
+    def general_get_directory(self) -> str:
+        return self.directory
+    

bbp_ng/UTIL_file_io.py

@@ -0,0 +1,91 @@
+import bpy, mathutils
+import struct, os, io, typing
+from . import UTIL_virtools_types
+
+## MARK:
+#  This module may be deprecated because the host refering this module, 
+#  BM file import and export is no longer existing.
+
+_FileWriter_t = io.BufferedWriter
+_FileReader_t = io.BufferedReader
+
+#region Writer Functions
+
+def write_string(fs: _FileWriter_t, strl: str) -> None:
+    count = len(strl)
+    write_uint32(fs, count)
+    fs.write(strl.encode("utf_32_le"))
+
+def write_uint8(fs: _FileWriter_t, num: int) -> None:
+    fs.write(struct.pack("<B", num))
+
+def write_uint32(fs: _FileWriter_t, num: int) -> None:
+    fs.write(struct.pack("<I", num))
+
+def write_uint64(fs: _FileWriter_t, num: int) -> None:
+    fs.write(struct.pack("<Q", num))
+
+def write_bool(fs: _FileWriter_t, boolean: bool) -> None:
+    if boolean:
+        write_uint8(fs,  1)
+    else:
+        write_uint8(fs,  0)
+
+def write_float(fs: _FileWriter_t, fl: float) -> None:
+    fs.write(struct.pack("<f", fl))
+
+def write_world_matrix(fs: _FileWriter_t, mat: UTIL_virtools_types.VxMatrix) -> None:
+    fs.write(struct.pack("<16f", *mat.to_const()))
+
+def write_color(fs: _FileWriter_t, colors: UTIL_virtools_types.VxColor) -> None:
+    fs.write(struct.pack("<fff", *colors.to_const_rgb()))
+
+def write_uint32_array(fs: _FileWriter_t, vals: typing.Iterable[int], count: int) -> None:
+    fs.write(struct.pack('<' + str(count) + 'I', *vals))
+
+def write_float_array(fs: _FileWriter_t, vals: typing.Iterable[float], count: int) -> None:
+    fs.write(struct.pack('<' + str(count) + 'f', *vals))
+
+#endregion
+
+#region Reader Functions
+
+def peek_stream(fs: _FileReader_t) -> bytes:
+    res = fs.read(1)
+    fs.seek(-1, os.SEEK_CUR)
+    return res
+
+def read_float(fs: _FileReader_t) -> float:
+    return struct.unpack("f", fs.read(4))[0]
+
+def read_uint8(fs: _FileReader_t) -> int:
+    return struct.unpack("B", fs.read(1))[0]
+
+def read_uint32(fs: _FileReader_t) -> int:
+    return struct.unpack("I", fs.read(4))[0]
+
+def read_uint64(fs: _FileReader_t) -> int:
+    return struct.unpack("Q", fs.read(8))[0]
+
+def read_string(fs: _FileReader_t) -> str:
+    count = read_uint32(fs)
+    return fs.read(count * 4).decode("utf_32_le")
+
+def read_bool(fs: _FileReader_t) -> bool:
+    return read_uint8(fs) != 0
+
+def read_world_materix(fs: _FileReader_t, mat: UTIL_virtools_types.VxMatrix) -> None:
+    mat.from_const(struct.unpack("<16f", fs.read(16 * 4)))
+
+def read_color(fs: _FileReader_t, target: UTIL_virtools_types.VxColor) -> None:
+    target.from_const_rgb(struct.unpack("fff", fs.read(3 * 4)))
+
+def read_uint32_array(fs: _FileReader_t, count: int) -> tuple[int, ...]:
+    fmt: struct.Struct = struct.Struct('<' + str(count) + 'I')
+    return fmt.unpack(fs.read(fmt.size))
+
+def read_float_array(fs: _FileReader_t, count: int) -> tuple[float, ...]:
+    fmt: struct.Struct = struct.Struct('<' + str(count) + 'f')
+    return fmt.unpack(fs.read(fmt.size))
+
+#endregion

bbp_ng/UTIL_functions.py

@@ -0,0 +1,271 @@
+import bpy, mathutils
+import math, typing, enum, sys
+
+class BBPException(Exception):
+    """
+    The exception thrown by Ballance Blender Plugin
+    """
+    pass
+
+def clamp_float(v: float, min_val: float, max_val: float) -> float:
+    """!
+    @brief Clamp a float value
+
+    @param v[in] The value need to be clamp.
+    @param min_val[in] The allowed minium value, including self.
+    @param max_val[in] The allowed maxium value, including self.
+    @return Clamped value.
+    """
+    if (max_val < min_val): raise BBPException("Invalid range of clamp_float().")
+
+    if (v < min_val): return min_val
+    elif (v > max_val): return max_val
+    else: return v
+
+def clamp_int(v: int, min_val: int, max_val: int) -> int:
+    """!
+    @brief Clamp a int value
+
+    @param v[in] The value need to be clamp.
+    @param min_val[in] The allowed minium value, including self.
+    @param max_val[in] The allowed maxium value, including self.
+    @return Clamped value.
+    """
+    if (max_val < min_val): raise BBPException("Invalid range of clamp_int().")
+
+    if (v < min_val): return min_val
+    elif (v > max_val): return max_val
+    else: return v
+
+def message_box(message: tuple[str, ...], title: str, icon: str):
+    """
+    Show a message box in Blender. Non-block mode.
+
+    @param message[in] The text this message box displayed. Each item in this param will show as a single line.
+    @param title[in] Message box title text.
+    @param icon[in] The icon this message box displayed.
+    """
+    def draw(self, context: bpy.types.Context):
+        layout = self.layout
+        for item in message:
+            layout.label(text=item, translate=False)
+
+    bpy.context.window_manager.popup_menu(draw, title = title, icon = icon)
+
+def add_into_scene(obj: bpy.types.Object):
+    view_layer = bpy.context.view_layer
+    collection = view_layer.active_layer_collection.collection
+    collection.objects.link(obj)
+
+def move_to_cursor(obj: bpy.types.Object):
+    # use obj.matrix_world to move, not obj.location because this bug:
+    # https://blender.stackexchange.com/questions/27667/incorrect-matrix-world-after-transformation
+    # the update of matrix_world after setting location is not immediately.
+    # and calling update() function for view_layer for the translation of each object is not suit for too much objects.
+
+    # obj.location = bpy.context.scene.cursor.location
+    obj.matrix_world = obj.matrix_world @ mathutils.Matrix.Translation(bpy.context.scene.cursor.location - obj.location)
+
+def add_into_scene_and_move_to_cursor(obj: bpy.types.Object):
+    add_into_scene(obj)
+    move_to_cursor(obj)
+
+def select_certain_objects(objs: tuple[bpy.types.Object, ...]) -> None:
+    # deselect all objects first
+    bpy.ops.object.select_all(action = 'DESELECT')
+    # if no objects, return
+    if len(objs) == 0: return
+
+    # set selection for each object
+    for obj in objs:
+        obj.select_set(True)
+    # select first object as active object
+    bpy.context.view_layer.objects.active = objs[0]
+
+def is_in_object_mode() -> bool:
+    # get active object from context
+    obj = bpy.context.active_object
+
+    # if there is no active object, we think it is in object mode
+    if obj is None: return True
+
+    # simply check active object mode
+    return obj.mode == 'OBJECT'
+
+class EnumPropHelper():
+    """
+    These class contain all functions related to EnumProperty, including generating `items`, 
+    parsing data from EnumProperty string value and getting EnumProperty acceptable string format from data.
+    """
+
+    # define some type hint
+    _TFctToStr = typing.Callable[[typing.Any], str]
+    _TFctFromStr = typing.Callable[[str], typing.Any]
+    _TFctName = typing.Callable[[typing.Any], str]
+    _TFctDesc = typing.Callable[[typing.Any], str]
+    _TFctIcon = typing.Callable[[typing.Any], str | int]
+
+    # define class member
+
+    __mCollections: typing.Iterable[typing.Any]
+    __mFctToStr: _TFctToStr
+    __mFctFromStr: _TFctFromStr
+    __mFctName: _TFctName
+    __mFctDesc: _TFctDesc
+    __mFctIcon: _TFctIcon
+
+    def __init__(
+            self, 
+            collections_: typing.Iterable[typing.Any],
+            fct_to_str: _TFctToStr,
+            fct_from_str: _TFctFromStr,
+            fct_name: _TFctName,
+            fct_desc: _TFctDesc,
+            fct_icon: _TFctIcon):
+        """
+        Initialize a EnumProperty helper.
+
+        @param collections_ [in] The collection all available enum property entries contained.
+        It can be enum.Enum or a simple list/tuple/dict.
+        @param fct_to_str [in] A function pointer converting data collection member to its string format.
+        For enum.IntEnum, it can be simply `lambda x: str(x.value)`
+        @param fct_from_str [in] A function pointer getting data collection member from its string format.
+        For enum.IntEnum, it can be simply `lambda x: TEnum(int(x))`
+        @param fct_name [in] A function pointer converting data collection member to its display name.
+        @param fct_desc [in] Same as `fct_name` but return description instead. Return empty string, not None if no description.
+        @param fct_icon [in] Same as `fct_name` but return the used icon instead. Return empty string if no icon.
+        """
+        # assign member
+        self.__mCollections = collections_
+        self.__mFctToStr = fct_to_str
+        self.__mFctFromStr = fct_from_str
+        self.__mFctName = fct_name
+        self.__mFctDesc = fct_desc
+        self.__mFctIcon = fct_icon
+
+    def generate_items(self) -> tuple[tuple[str, str, str, int | str, int], ...]:
+        """
+        Generate a tuple which can be applied to Blender EnumProperty's "items".
+        """
+        # blender enum prop item format:
+        # (token, display name, descriptions, icon, index)
+        return tuple(
+            (
+                self.__mFctToStr(member),   # call to_str as its token.
+                self.__mFctName(member), 
+                self.__mFctDesc(member), 
+                self.__mFctIcon(member), 
+                idx # use hardcode index, not the collection member self.
+            ) for idx, member in enumerate(self.__mCollections)
+        )
+    
+    def get_selection(self, prop: str) -> typing.Any:
+        """
+        Return collection member from given Blender EnumProp string data.
+        """
+        # call from_str fct ptr
+        return self.__mFctFromStr(prop)
+    
+    def to_selection(self, val: typing.Any) -> str:
+        """
+        Parse collection member to Blender EnumProp acceptable string format.
+        """
+        # call to_str fct ptr
+        return self.__mFctToStr(val)
+
+#region Blender Collection Visitor
+
+_TPropertyGroup = typing.TypeVar('_TPropertyGroup', bound = bpy.types.PropertyGroup)
+
+class CollectionVisitor(typing.Generic[_TPropertyGroup]):
+    """
+    This is a patch class for Blender collection property.
+    Blender collcetion property lack essential type hint and document.
+    So I create a wrapper for my personal use to reduce type hint errors raised by my linter.
+    """
+
+    __mSrcProp: bpy.types.CollectionProperty
+
+    def __init__(self, src_prop: bpy.types.CollectionProperty):
+        self.__mSrcProp = src_prop
+
+    def add(self) -> _TPropertyGroup:
+        """!
+        @brief Adds a new item to the collection.
+        @return The instance of newly created item.
+        """
+        return self.__mSrcProp.add()
+
+    def remove(self, index: int) -> None:
+        """!
+        @brief Removes the item at the specified index from the collection.
+        @param[in] index The index of the item to remove.
+        """
+        self.__mSrcProp.remove(index)
+
+    def move(self, from_index: int, to_index: int) -> None:
+        """!
+        @brief Moves an item from one index to another within the collection.
+        @param[in] from_index The current index of the item to move.
+        @param[in] to_index The target index where the item should be moved.
+        """
+        self.__mSrcProp.move(from_index, to_index)
+
+    def clear(self) -> None:
+        """!
+        @brief Clears all items from the collection.
+        """
+        self.__mSrcProp.clear()
+
+    def __len__(self) -> int:
+        return self.__mSrcProp.__len__()
+    def __getitem__(self, index: int | str) -> _TPropertyGroup:
+        return self.__mSrcProp.__getitem__(index)
+    def __setitem__(self, index: int | str, value: _TPropertyGroup) -> None:
+        self.__mSrcProp.__setitem__(index, value)
+    def __delitem__(self, index: int | str) -> None:
+        self.__mSrcProp.__delitem__(index)
+    def __iter__(self) -> typing.Iterator[_TPropertyGroup]:
+        return self.__mSrcProp.__iter__()
+    def __contains__(self, item: _TPropertyGroup) -> bool:
+        return self.__mSrcProp.__contains__(item)
+
+#endregion
+
+#region Tiny Mutex for With Context
+
+_TMutexObject = typing.TypeVar('_TMutexObject')
+
+class TinyMutex(typing.Generic[_TMutexObject]):
+    """
+    In this plugin, some class have "with" context feature.
+    However, it is essential to block any futher visiting if some "with" context are operating on some object.
+    This is the reason why this tiny mutex is designed.
+
+    Please note this class is not a real MUTEX.
+    We just want to make sure the resources only can be visited by one "with" context.
+    So it doesn't matter that we do not use lock before operating something.
+    """
+
+    __mProtectedObjects: set[_TMutexObject]
+
+    def __init__(self):
+        self.__mProtectedObjects = set()
+
+    def lock(self, obj: _TMutexObject) -> None:
+        if obj in self.__mProtectedObjects:
+            raise BBPException('It is not allowed that operate multiple "with" contexts on a single object.')
+        self.__mProtectedObjects.add(obj)
+
+    def try_lock(self, obj: _TMutexObject) -> bool:
+        if obj in self.__mProtectedObjects:
+            return False
+        self.__mProtectedObjects.add(obj)
+        return True
+
+    def unlock(self, obj: _TMutexObject) -> None:
+        if obj not in self.__mProtectedObjects:
+            raise BBPException('It is not allowed that unlock an non-existent object.')
+        self.__mProtectedObjects.remove(obj)
+
+#endregion

bbp_ng/UTIL_icons_manager.py

@@ -0,0 +1,113 @@
+import bpy, bpy.utils.previews
+import os, enum, typing
+
+class BlenderPresetIcons(enum.Enum):
+    Info = 'INFO'
+    Warning = 'ERROR'
+    Error = 'CANCEL'
+
+#region Custom Icons Helper
+
+_g_SupportedImageExts: set[str] = set((
+    '.png',
+))
+
+_g_IconsManager: bpy.utils.previews.ImagePreviewCollection | None = None
+
+_g_EmptyIcon: int = 0
+_g_IconPrefix: str = "BlcBldPlg_"
+
+_g_BmeIconsMap: dict[str, int] = {}
+_g_BmeIconPrefix: str = _g_IconPrefix + 'Bme_'
+_g_ComponentIconsMap: dict[str, int] = {}
+_g_ComponentIconPrefix: str = _g_IconPrefix + 'Component_'
+_g_GroupIconsMap: dict[str, int] = {}
+_g_GroupIconPrefix: str = _g_IconPrefix + 'Group_'
+
+def _iterate_folder_images(folder: str) -> typing.Iterator[tuple[str, str]]:
+    for name in os.listdir(folder):
+        # check whether it is file
+        filepath: str = os.path.join(folder, name)
+        if os.path.isfile(filepath):
+            # check file exts
+            (root, ext) = os.path.splitext(name)
+            if ext.lower() in _g_SupportedImageExts:
+                yield (filepath, root)
+
+def _load_image_folder(
+        folder: str, 
+        loader: bpy.utils.previews.ImagePreviewCollection, 
+        container: dict[str, int],
+        name_prefix: str) -> None:
+    # iterate folder
+    for (filepath, filename_no_ext) in _iterate_folder_images(folder):
+        # generate name for unique
+        icon_name: str = name_prefix + filename_no_ext
+        # load it
+        loader.load(icon_name, filepath, 'IMAGE')
+        # add into list. use plain name (not the unique name)
+        container[filename_no_ext] = loader[icon_name].icon_id
+
+#endregion
+
+#region Custom Icons Visitors
+
+def get_empty_icon() -> int:
+    return _g_EmptyIcon
+
+def get_bme_icon(name: str) -> int | None:
+    return _g_BmeIconsMap.get(name, None)
+
+def get_component_icon(name: str) -> int | None:
+    return _g_ComponentIconsMap.get(name, None)
+
+def get_group_icon(name: str) -> int | None:
+    return _g_GroupIconsMap.get(name, None)
+
+#endregion
+
+def register() -> None:
+    global _g_IconsManager
+    global _g_EmptyIcon
+    global _g_BmeIconsMap, _g_ComponentIconsMap, _g_GroupIconsMap
+
+    # create preview collection and get icon folder
+    icons_folder: str = os.path.join(os.path.dirname(__file__), "icons")
+    _g_IconsManager = bpy.utils.previews.new()
+
+    # load empty icon as default fallback
+    empty_icon_name: str = _g_IconPrefix + 'EmptyIcon'
+    _g_IconsManager.load(empty_icon_name, os.path.join(icons_folder, "Empty.png"), 'IMAGE')
+    _g_EmptyIcon = _g_IconsManager[empty_icon_name].icon_id
+
+    # load bme, component, group icon
+    _load_image_folder(
+        os.path.join(icons_folder, 'bme'),
+        _g_IconsManager,
+        _g_BmeIconsMap,
+        _g_BmeIconPrefix
+    )
+    _load_image_folder(
+        os.path.join(icons_folder, 'component'),
+        _g_IconsManager,
+        _g_ComponentIconsMap,
+        _g_ComponentIconPrefix
+    )
+    _load_image_folder(
+        os.path.join(icons_folder, 'group'),
+        _g_IconsManager,
+        _g_GroupIconsMap,
+        _g_GroupIconPrefix
+    )
+
+def unregister() -> None:
+    global _g_IconsManager
+    global _g_EmptyIcon
+    global _g_BmeIconsMap, _g_ComponentIconsMap, _g_GroupIconsMap
+
+    bpy.utils.previews.remove(_g_IconsManager)
+    _g_IconsManager = None
+
+    _g_BmeIconsMap.clear()
+    _g_ComponentIconsMap.clear()
+    _g_GroupIconsMap.clear()

bbp_ng/UTIL_ioport_shared.py

@@ -0,0 +1,389 @@
+import bpy
+import enum, typing
+from . import UTIL_virtools_types, UTIL_functions
+from . import PROP_ptrprop_resolver, PROP_ballance_map_info
+
+## Intent
+#  Some importer or exporter may share same properties.
+#  So we create some shared class and user just need inherit them 
+#  and call general getter to get user selected data.
+#  Also provide draw function thus caller do not need draw the params themselves.
+
+class ConflictStrategy(enum.IntEnum):
+    Rename = enum.auto()
+    Current = enum.auto()
+_g_ConflictStrategyDesc: dict[ConflictStrategy, tuple[str, str]] = {
+    ConflictStrategy.Rename: ('Rename', 'Rename the new one'),
+    ConflictStrategy.Current: ('Use Current', 'Use current one'),
+}
+_g_EnumHelper_ConflictStrategy: UTIL_functions.EnumPropHelper = UTIL_functions.EnumPropHelper(
+    ConflictStrategy,
+    lambda x: str(x.value),
+    lambda x: ConflictStrategy(int(x)),
+    lambda x: _g_ConflictStrategyDesc[x][0],
+    lambda x: _g_ConflictStrategyDesc[x][1],
+    lambda _: ''
+)
+
+#region Assist Classes
+
+class ExportEditModeBackup():
+    """
+    The class which save Edit Mode when exporting and restore it after exporting.
+    Because edit mode is not allowed when exporting.
+    Support `with` statement.
+
+    ```
+    with ExportEditModeBackup():
+        # do some exporting work
+        blabla()
+    # restore automatically when exiting "with"
+    ```
+    """
+    mInEditMode: bool
+
+    def __init__(self):
+        if bpy.context.object and bpy.context.object.mode == "EDIT":
+            # set and toggle it. otherwise exporting will failed.
+            self.mInEditMode = True
+            bpy.ops.object.editmode_toggle()
+        else:
+            self.mInEditMode = False
+    
+    def __enter__(self):
+        return self
+    
+    def __exit__(self, exc_type, exc_value, traceback):
+        if self.mInEditMode:
+            bpy.ops.object.editmode_toggle()
+            self.mInEditMode = False
+    
+class ConflictResolver():
+    """
+    This class frequently used when importing objects.
+    This class accept 4 conflict strategies for object, mesh, material and texture,
+    and provide 4 general creation functions to handle these strategies.
+    Each general creation functions will return an instance and a bool indicating whether this instance need be initialized.
+    """
+    
+    __mObjectStrategy: ConflictStrategy
+    __mLightStrategy: ConflictStrategy
+    __mMeshStrategy: ConflictStrategy
+    __mMaterialStrategy: ConflictStrategy
+    __mTextureStrategy: ConflictStrategy
+
+    def __init__(self, 
+            obj_strategy: ConflictStrategy, 
+            light_strategy: ConflictStrategy, 
+            mesh_strategy: ConflictStrategy, 
+            mtl_strategy: ConflictStrategy, 
+            tex_strategy: ConflictStrategy):
+        self.__mObjectStrategy = obj_strategy
+        self.__mLightStrategy = light_strategy
+        self.__mMeshStrategy = mesh_strategy
+        self.__mMaterialStrategy = mtl_strategy
+        self.__mTextureStrategy = tex_strategy
+
+    def create_object(self, name: str, data: bpy.types.Mesh | None) -> tuple[bpy.types.Object, bool]:
+        """
+        Create object according to conflict strategy.
+        `data` will only be applied when creating new object (no existing instance or strategy order rename).
+
+        Please note this function is only used to create mesh 3d object.
+        If you want to create light object, please use other functions provided by this class.
+        The 3d object and data block of light is created together.
+        """
+        if self.__mObjectStrategy == ConflictStrategy.Current:
+            old: bpy.types.Object | None = bpy.data.objects.get(name, None)
+            if old is not None:
+                return (old, False)
+        return (bpy.data.objects.new(name, data), True)
+    
+    def create_light(self, name: str) -> tuple[bpy.types.Object, bpy.types.Light, bool]:
+        """
+        Create light data block and associated 3d object.
+
+        If conflict strategy is "Current", we try fetch 3d object with given name first,
+        then check whether it is light.
+        If no given name object or this object is not light, we create a new one,
+        otherwise return old one.
+        """
+        if self.__mLightStrategy == ConflictStrategy.Current:
+            old_obj: bpy.types.Object | None = bpy.data.objects.get(name, None)
+            if old_obj is not None and old_obj.type == 'LIGHT':
+                return (old_obj, typing.cast(bpy.types.Light, old_obj.data), False)
+        # create new object.
+        # if object or light name is conflict, rename it directly without considering conflict strategy.
+        # create light with default point light type
+        new_light: bpy.types.Light = bpy.data.lights.new(name, 'POINT')
+        new_obj: bpy.types.Object = bpy.data.objects.new(name, new_light)
+        return (new_obj, new_light, True)
+
+    def create_mesh(self, name: str) -> tuple[bpy.types.Mesh, bool]:
+        if self.__mMeshStrategy == ConflictStrategy.Current:
+            old: bpy.types.Mesh | None = bpy.data.meshes.get(name, None)
+            if old is not None:
+                return (old, False)
+        return (bpy.data.meshes.new(name), True)
+    
+    def create_material(self, name: str) -> tuple[bpy.types.Material, bool]:
+        if self.__mMaterialStrategy == ConflictStrategy.Current:
+            old: bpy.types.Material | None = bpy.data.materials.get(name, None)
+            if old is not None:
+                return (old, False)
+        return (bpy.data.materials.new(name), True)
+    
+    def create_texture(self, name: str, fct_cret: typing.Callable[[], bpy.types.Image]) -> tuple[bpy.types.Image, bool]:
+        """
+        Create texture according to conflict strategy.
+        If the strategy order current, it will return current existing instance.
+        If no existing instance or strategy order rename, it will call `fct_cret` to create new texture.
+
+        Because texture do not have a general creation function, we frequently create it by other modules provided texture functions.
+        So `fct_cret` is the real creation function. And it will not be executed if no creation happended.
+        """
+        if self.__mTextureStrategy == ConflictStrategy.Current:
+            old: bpy.types.Image | None = bpy.data.images.get(name, None)
+            if old is not None:
+                return (old, False)
+        # create texture, set name, and return
+        tex: bpy.types.Image = fct_cret()
+        tex.name = name
+        return (tex, True)
+
+#endregion
+
+class ImportParams():
+    texture_conflict_strategy: bpy.props.EnumProperty(
+        name = "Texture Name Conflict",
+        items = _g_EnumHelper_ConflictStrategy.generate_items(),
+        description = "Define how to process texture name conflict",
+        default = _g_EnumHelper_ConflictStrategy.to_selection(ConflictStrategy.Current),
+        translation_context = 'BBP/UTIL_ioport_shared.ImportParams/property'
+    ) # type: ignore
+
+    material_conflict_strategy: bpy.props.EnumProperty(
+        name = "Material Name Conflict",
+        items = _g_EnumHelper_ConflictStrategy.generate_items(),
+        description = "Define how to process material name conflict",
+        default = _g_EnumHelper_ConflictStrategy.to_selection(ConflictStrategy.Rename),
+        translation_context = 'BBP/UTIL_ioport_shared.ImportParams/property'
+    ) # type: ignore
+
+    mesh_conflict_strategy: bpy.props.EnumProperty(
+        name = "Mesh Name Conflict",
+        items = _g_EnumHelper_ConflictStrategy.generate_items(),
+        description = "Define how to process mesh name conflict",
+        default = _g_EnumHelper_ConflictStrategy.to_selection(ConflictStrategy.Rename),
+        translation_context = 'BBP/UTIL_ioport_shared.ImportParams/property'
+    ) # type: ignore
+
+    light_conflict_strategy: bpy.props.EnumProperty(
+        name = "Light Name Conflict",
+        items = _g_EnumHelper_ConflictStrategy.generate_items(),
+        description = "Define how to process light name conflict",
+        default = _g_EnumHelper_ConflictStrategy.to_selection(ConflictStrategy.Rename),
+        translation_context = 'BBP/UTIL_ioport_shared.ImportParams/property'
+    ) # type: ignore
+
+    object_conflict_strategy: bpy.props.EnumProperty(
+        name = "Object Name Conflict",
+        items = _g_EnumHelper_ConflictStrategy.generate_items(),
+        description = "Define how to process object name conflict",
+        default = _g_EnumHelper_ConflictStrategy.to_selection(ConflictStrategy.Rename),
+        translation_context = 'BBP/UTIL_ioport_shared.ImportParams/property'
+    ) # type: ignore
+
+    def draw_import_params(self, layout: bpy.types.UILayout) -> None:
+        header: bpy.types.UILayout
+        body: bpy.types.UILayout
+        header, body = layout.panel("BBP_PT_ioport_shared_import_params", default_closed=False)
+        header.label(text='Import Parameters', text_ctxt='BBP/UTIL_ioport_shared.ImportParams/draw')
+        # NOTE: if panel is collapsed, body will be None. So we need check it.
+        if body is None: return
+
+        body.label(text='Name Conflict Strategy', text_ctxt='BBP/UTIL_ioport_shared.ImportParams/draw')
+        grid = body.grid_flow(row_major=False, columns=2)
+        grid.label(text='Object', icon='CUBE', text_ctxt='BBP/UTIL_ioport_shared.ImportParams/draw')
+        grid.label(text='Light', icon='LIGHT', text_ctxt='BBP/UTIL_ioport_shared.ImportParams/draw')
+        grid.label(text='Mesh', icon='MESH_DATA', text_ctxt='BBP/UTIL_ioport_shared.ImportParams/draw')
+        grid.label(text='Material', icon='MATERIAL', text_ctxt='BBP/UTIL_ioport_shared.ImportParams/draw')
+        grid.label(text='Texture', icon='TEXTURE', text_ctxt='BBP/UTIL_ioport_shared.ImportParams/draw')
+        grid.prop(self, 'object_conflict_strategy', text='')
+        grid.prop(self, 'light_conflict_strategy', text='')
+        grid.prop(self, 'mesh_conflict_strategy', text='')
+        grid.prop(self, 'material_conflict_strategy', text='')
+        grid.prop(self, 'texture_conflict_strategy', text='')
+
+    def general_get_texture_conflict_strategy(self) -> ConflictStrategy:
+        return _g_EnumHelper_ConflictStrategy.get_selection(self.texture_conflict_strategy)
+
+    def general_get_material_conflict_strategy(self) -> ConflictStrategy:
+        return _g_EnumHelper_ConflictStrategy.get_selection(self.material_conflict_strategy)
+
+    def general_get_mesh_conflict_strategy(self) -> ConflictStrategy:
+        return _g_EnumHelper_ConflictStrategy.get_selection(self.mesh_conflict_strategy)
+
+    def general_get_light_conflict_strategy(self) -> ConflictStrategy:
+        return _g_EnumHelper_ConflictStrategy.get_selection(self.light_conflict_strategy)
+
+    def general_get_object_conflict_strategy(self) -> ConflictStrategy:
+        return _g_EnumHelper_ConflictStrategy.get_selection(self.object_conflict_strategy)
+
+    def general_get_conflict_resolver(self) -> ConflictResolver:
+        return ConflictResolver(
+            self.general_get_object_conflict_strategy(),
+            self.general_get_light_conflict_strategy(),
+            self.general_get_mesh_conflict_strategy(),
+            self.general_get_material_conflict_strategy(),
+            self.general_get_texture_conflict_strategy()
+        )
+
+class ExportParams():
+    export_mode: bpy.props.EnumProperty(
+        name = "Export Mode",
+        items = (
+            ('COLLECTION', "Collection", "Export a collection", 'OUTLINER_COLLECTION', 0),
+            ('OBJECT', "Object", "Export an object", 'OBJECT_DATA', 1),
+        ),
+        translation_context = 'BBP/UTIL_ioport_shared.ExportParams/property'
+    ) # type: ignore
+
+    def draw_export_params(self, context: bpy.types.Context, layout: bpy.types.UILayout) -> None:
+        header: bpy.types.UILayout
+        body: bpy.types.UILayout
+        header, body = layout.panel("BBP_PT_ioport_shared_export_params", default_closed=False)
+        header.label(text='Export Parameters', text_ctxt='BBP/UTIL_ioport_shared.ExportParams/draw')
+        if body is None: return
+
+        # make prop expand horizontaly, not vertical.
+        horizon_body = body.row()
+        # draw switch
+        horizon_body.prop(self, "export_mode", expand=True)
+
+        # draw picker
+        ptrprops = PROP_ptrprop_resolver.PropsVisitor(context.scene)
+        if self.export_mode == 'COLLECTION':
+            ptrprops.draw_export_collection(body)
+        elif self.export_mode == 'OBJECT':
+            ptrprops.draw_export_object(body)
+
+    def general_get_export_objects(self, context: bpy.types.Context) -> tuple[bpy.types.Object] | None:
+        """
+        Return resolved exported objects or None if no selection.
+        """
+        ptrprops = PROP_ptrprop_resolver.PropsVisitor(context.scene)
+        if self.export_mode == 'COLLECTION':
+            col: bpy.types.Collection = ptrprops.get_export_collection()
+            if col is None: return None
+            else:
+                return tuple(col.all_objects)
+        else:
+            obj: bpy.types.Object = ptrprops.get_export_object()
+            if obj is None: return None
+            else: return (obj, )
+
+# define global tex save opt blender enum prop helper
+_g_EnumHelper_CK_TEXTURE_SAVEOPTIONS: UTIL_virtools_types.EnumPropHelper = UTIL_virtools_types.EnumPropHelper(UTIL_virtools_types.CK_TEXTURE_SAVEOPTIONS)
+
+class VirtoolsParams():
+    texture_save_opt: bpy.props.EnumProperty(
+        name = "Global Texture Save Options",
+        description = "Decide how texture saved if texture is specified as Use Global as its Save Options.",
+        items = _g_EnumHelper_CK_TEXTURE_SAVEOPTIONS.generate_items(),
+        default = _g_EnumHelper_CK_TEXTURE_SAVEOPTIONS.to_selection(UTIL_virtools_types.CK_TEXTURE_SAVEOPTIONS.CKTEXTURE_EXTERNAL),
+        translation_context = 'BBP/UTIL_ioport_shared.VirtoolsParams/property'
+    ) # type: ignore
+
+    use_compress: bpy.props.BoolProperty(
+        name="Use Compress",
+        description = "Whether use ZLib to compress result when saving composition.",
+        default = True,
+        translation_context = 'BBP/UTIL_ioport_shared.VirtoolsParams/property'
+    ) # type: ignore
+
+    compress_level: bpy.props.IntProperty(
+        name = "Compress Level",
+        description = "The ZLib compress level used by Virtools Engine when saving composition.",
+        min = 1, max = 9,
+        default = 5,
+        translation_context = 'BBP/UTIL_ioport_shared.VirtoolsParams/property'
+    ) # type: ignore
+
+    def draw_virtools_params(self, context: bpy.types.Context, layout: bpy.types.UILayout, is_importer: bool) -> None:
+        header: bpy.types.UILayout
+        body: bpy.types.UILayout
+        header, body = layout.panel("BBP_PT_ioport_shared_virtools_params", default_closed=False)
+        header.label(text='Virtools Parameters', text_ctxt='BBP/UTIL_ioport_shared.VirtoolsParams/draw')
+        if body is None: return
+
+        # draw encodings
+        body.label(text='Encodings', text_ctxt='BBP/UTIL_ioport_shared.VirtoolsParams/draw')
+        ptrprops = PROP_ptrprop_resolver.PropsVisitor(context.scene)
+        ptrprops.draw_ioport_encodings(body)
+
+        # following field are only valid in exporter
+        if not is_importer:
+            body.separator()
+            body.label(text='Global Texture Save Options', text_ctxt='BBP/UTIL_ioport_shared.VirtoolsParams/draw')
+            body.prop(self, 'texture_save_opt', text='')
+
+            body.separator()
+            body.label(text='Compression', text_ctxt='BBP/UTIL_ioport_shared.VirtoolsParams/draw')
+            body.prop(self, 'use_compress')
+            if self.use_compress:
+                body.prop(self, 'compress_level')
+
+
+    def general_get_vt_encodings(self, context: bpy.types.Context) -> tuple[str, ...]:
+        # get from ptrprop resolver then filter empty item
+        ptrprops = PROP_ptrprop_resolver.PropsVisitor(context.scene)
+        return tuple(filter(lambda encoding: len(encoding) != 0, ptrprops.get_ioport_encodings()))
+
+    def general_get_texture_save_opt(self) -> UTIL_virtools_types.CK_TEXTURE_SAVEOPTIONS:
+        return _g_EnumHelper_CK_TEXTURE_SAVEOPTIONS.get_selection(self.texture_save_opt)
+
+    def general_get_use_compress(self) -> bool:
+        return self.use_compress
+
+    def general_get_compress_level(self) -> int:
+        return self.compress_level
+    
+class BallanceParams():
+    successive_sector: bpy.props.BoolProperty(
+        name="Successive Sector",
+        description = "Whether order exporter to use document specified sector count to make sure sector is successive.",
+        default = True,
+        translation_context = 'BBP/UTIL_ioport_shared.BallanceParams/property'
+    ) # type: ignore
+
+    def draw_ballance_params(self, layout: bpy.types.UILayout, is_importer: bool) -> None:
+        # ballance params only presented in exporter.
+        # so if we are in impoerter, we skip the whole function
+        # because we don't want to create an empty panel.
+        if is_importer: return
+
+        header: bpy.types.UILayout
+        body: bpy.types.UILayout
+        header, body = layout.panel("BBP_PT_ioport_shared_ballance_params", default_closed=False)
+        header.label(text='Ballance Parameters', text_ctxt='BBP/UTIL_ioport_shared.BallanceParams/draw')
+        if body is None: return
+
+        map_info: PROP_ballance_map_info.RawBallanceMapInfo = PROP_ballance_map_info.get_raw_ballance_map_info(bpy.context.scene)
+        body.prop(self, 'successive_sector')
+        tr_text: str = bpy.app.translations.pgettext_iface(
+            'Map Sectors: {0}', 'BBP/UTIL_ioport_shared.BallanceParams/draw')
+        body.label(text=tr_text.format(map_info.mSectorCount), translate=False)
+
+    def general_get_successive_sector(self) -> bool:
+        return self.successive_sector
+
+    def general_get_successive_sector_count(self) -> int:
+        # if user do not pick successive sector, return a random int directly.
+        if not self.general_get_successive_sector():
+            return 0
+        
+        # otherwise fetch user specified sector number
+        map_info: PROP_ballance_map_info.RawBallanceMapInfo
+        map_info = PROP_ballance_map_info.get_raw_ballance_map_info(bpy.context.scene)
+        return map_info.mSectorCount

bbp_ng/UTIL_naming_convension.py

@@ -0,0 +1,669 @@
+import bpy
+import typing, enum, re
+from . import UTIL_functions
+from . import PROP_virtools_group
+
+#region Rename Error Reporter
+
+class _RenameErrorType(enum.IntEnum):
+    ERROR = enum.auto()
+    WARNING = enum.auto()
+    INFO = enum.auto()
+
+class _RenameErrorItem():
+    mErrType: _RenameErrorType
+    mDescription: str
+
+    def __init__(self, err_t: _RenameErrorType, description: str):
+        self.mErrType = err_t
+        self.mDescription = description
+
+class RenameErrorReporter():
+    """
+    A basic 'rename error report' using simple prints in console.
+
+    This object can be used as a context manager.
+
+    It supports multiple levels of 'substeps' - you shall always enter at least one substep (because level 0
+    has only one single step, representing the whole 'area' of the progress stuff).
+
+    You should give the object renaming of substeps each time you enter a new one.
+
+    Leaving a substep automatically steps by one the parent level.
+
+    ```
+    with RenameErrorReporter() as reporter:
+        progress.enter_object(obj)
+
+        # process for object with reporter
+        reporter.add_error('fork!')
+
+        progress.leave_object()
+    ```
+    """
+    mAllObjCounter: int
+    mFailedObjCounter: int
+
+    mErrList: list[_RenameErrorItem]
+    mOldName: str
+    mHasError: bool
+
+    def __init__(self):
+        self.mAllObjCounter = 0
+        self.mFailedObjCounter = 0
+        
+        self.mErrList = []
+        self.mOldName = ""
+        self.mHasError = False
+
+    def add_error(self, description: str):
+        self.mHasError = True
+        self.mErrList.append(_RenameErrorItem(_RenameErrorType.ERROR, description))
+    def add_warning(self, description: str):
+        self.mErrList.append(_RenameErrorItem(_RenameErrorType.WARNING, description))
+    def add_info(self, description: str):
+        self.mErrList.append(_RenameErrorItem(_RenameErrorType.INFO, description))
+
+    def get_all_objs_count(self) -> int: return self.mAllObjCounter
+    def get_failed_objs_count(self) -> int: return self.mFailedObjCounter
+
+    def __enter__(self):
+        # print console report header
+        print('============')
+        print(bpy.app.translations.pgettext_rpt(
+            'Rename Report',
+            'BBP/UTIL_naming_convension.RenameErrorReporter'
+        ))
+        print('------------')
+        # return self as context
+        return self
+    
+    def __exit__(self, exc_type, exc_value, traceback):
+        # print console report tail
+        print('------------')
+        tr_text: str = bpy.app.translations.pgettext_rpt(
+            'All / Failed - {0} / {1}', 'BBP/UTIL_naming_convension.RenameErrorReporter')
+        print(tr_text.format(self.mAllObjCounter, self.mFailedObjCounter))
+        print('============')
+        # reset variables
+        self.mAllObjCounter = 0
+        self.mFailedObjCounter = 0
+    
+    def enter_object(self, obj: bpy.types.Object) -> None:
+        # inc all counter
+        self.mAllObjCounter += 1
+        # assign old name
+        self.mOldName = obj.name
+    def leave_object(self, obj:bpy.types.Object) -> None:
+        # if error list is empty, no need to report
+        if len(self.mErrList) == 0: return
+
+        # inc failed if necessary
+        if self.mHasError:
+            self.mFailedObjCounter += 1
+
+        # output header
+        # if new name is different with old name, output both of them
+        tr_text: str
+        new_name: str = obj.name
+        if self.mOldName == new_name:
+            tr_text = bpy.app.translations.pgettext_rpt('For object "{0}"', 'BBP/UTIL_naming_convension.RenameErrorReporter')
+            print(tr_text.format(new_name))
+        else:
+            tr_text = bpy.app.translations.pgettext_rpt('For object "{0}" (Old name: "{1}")', 'BBP/UTIL_naming_convension.RenameErrorReporter')
+            print(tr_text.format(new_name, self.mOldName))
+
+        # output error list with indent
+        for item in self.mErrList:
+            print('\t' + RenameErrorReporter.__erritem_to_string(item))
+
+        # clear error list for next object
+        self.mErrList.clear()
+        self.mHasError = False
+
+    @staticmethod
+    def __errtype_to_string(err_v: _RenameErrorType) -> str:
+        match(err_v):
+            case _RenameErrorType.ERROR:
+                return bpy.app.translations.pgettext_rpt('ERROR', 'BBP/UTIL_naming_convension.RenameErrorReporter')
+            case _RenameErrorType.WARNING:
+                return bpy.app.translations.pgettext_rpt('WARN', 'BBP/UTIL_naming_convension.RenameErrorReporter')
+            case _RenameErrorType.INFO:
+                return bpy.app.translations.pgettext_rpt('INFO', 'BBP/UTIL_naming_convension.RenameErrorReporter')
+            case _: raise UTIL_functions.BBPException("Unknown error type.")
+    @staticmethod
+    def __erritem_to_string(item: _RenameErrorItem) -> str:
+        return f'[{RenameErrorReporter.__errtype_to_string(item.mErrType)}]\t{item.mDescription}'
+
+#endregion
+
+#region Naming Convention Used Types
+
+class BallanceObjectType(enum.IntEnum):
+    COMPONENT = enum.auto()
+
+    FLOOR = enum.auto()
+    RAIL = enum.auto()
+    WOOD = enum.auto()
+    STOPPER = enum.auto()
+
+    LEVEL_START = enum.auto()
+    LEVEL_END = enum.auto()
+    CHECKPOINT = enum.auto()
+    RESETPOINT = enum.auto()
+
+    DEPTH_CUBE = enum.auto()
+    SKYLAYER = enum.auto()
+
+    DECORATION = enum.auto()
+
+class BallanceObjectInfo():
+    mBasicType: BallanceObjectType
+
+    ## Only available for COMPONENT basic type
+    mComponentType: str | None
+    ## Only available for COMPONENT, CHECKPOINT, RESETPOINT basic type
+    #  For COMPONENT, it indicate which sector this component belong to.
+    #  For CHECKPOINT, RESETPOINT, it indicate the index of this object.
+    #  In CHECKPOINT, RESETPOINT mode, the sector actually is the suffix number of these objects' name. So checkpoint starts with 1, not 0.
+    mSector: int | None
+
+    def __init__(self, basic_type: BallanceObjectType):
+        self.mBasicType = basic_type
+
+    @classmethod
+    def create_from_component(cls, comp_type: str, sector: int):
+        inst = cls(BallanceObjectType.COMPONENT)
+        inst.mComponentType = comp_type
+        inst.mSector = sector
+        return inst
+    
+    @classmethod
+    def create_from_checkpoint(cls, sector: int):
+        inst = cls(BallanceObjectType.CHECKPOINT)
+        inst.mSector = sector
+        return inst
+    @classmethod
+    def create_from_resetpoint(cls, sector: int):
+        inst = cls(BallanceObjectType.RESETPOINT)
+        inst.mSector = sector
+        return inst
+
+    @classmethod
+    def create_from_others(cls, basic_type: BallanceObjectType):
+        return cls(basic_type)
+
+#endregion
+
+#region Sector Extractor
+
+_g_RegexBlcSectorGroup: re.Pattern = re.compile('^Sector_(0[1-8]|[1-9][0-9]{1,2}|9)$')
+
+def extract_sector_from_name(group_name: str) -> int | None:
+    """
+    A convenient function to extract sector index from given group name.
+    This function also supports 999 sector plugin.
+
+    Not only in this module, but also in outside modules, this function is vary used to extract sector index info.
+
+    Function return the index extracted, or None if given group name is not a valid sector group.
+    The valid sector index is range from 1 to 999 (inclusive)
+    """
+    regex_result = _g_RegexBlcSectorGroup.match(group_name)
+    if regex_result is not None:
+        return int(regex_result.group(1))
+    else:
+        return None
+
+def build_name_from_sector_index(sector_index: int) -> str:
+    """
+    A convenient function to build Ballance recognizable sector group name.
+    This function also supports 999 sector plugin.
+
+    This function also is used in this module or other modules outside.
+    
+    Function return a sector name string. It basically the reverse operation of `extract_sector_from_name`.
+    """
+    if sector_index == 9:
+        return 'Sector_9'
+    else:
+        return f'Sector_{sector_index:0>2d}'
+
+#endregion
+
+#region Naming Convention Declaration
+
+_g_BlcNormalComponents: set[str] = set((
+    "P_Extra_Life",
+    "P_Extra_Point",
+    "P_Trafo_Paper",
+    "P_Trafo_Stone",
+    "P_Trafo_Wood",
+    "P_Ball_Paper",
+    "P_Ball_Stone",
+    "P_Ball_Wood",
+    "P_Box",
+    "P_Dome",
+    "P_Modul_01",
+    "P_Modul_03",
+    "P_Modul_08",
+    "P_Modul_17",
+    "P_Modul_18",
+    "P_Modul_19",
+    "P_Modul_25",
+    "P_Modul_26",
+    "P_Modul_29",
+    "P_Modul_30",
+    "P_Modul_34",
+    "P_Modul_37",
+    "P_Modul_41"
+))
+_g_BlcUniqueComponents: set[str] = set((
+    "PS_Levelstart",
+    "PE_Levelende",
+    "PC_Checkpoints",
+    "PR_Resetpoints"
+))
+_g_BlcFloor: set[str] = set((
+    "Sound_HitID_01",
+    "Sound_RollID_01"
+))
+_g_BlcWood: set[str] = set((
+    "Sound_HitID_02",
+    "Sound_RollID_02"
+))
+
+class VirtoolsGroupConvention():
+    cRegexComponent: typing.ClassVar[re.Pattern] = re.compile('^(' + '|'.join(_g_BlcNormalComponents) + ')_(0[1-9]|[1-9][0-9])_.*$')
+    cRegexPC: typing.ClassVar[re.Pattern] = re.compile('^PC_TwoFlames_(0[1-7])$')
+    cRegexPR: typing.ClassVar[re.Pattern] = re.compile('^PR_Resetpoint_(0[1-8])$')
+
+    @staticmethod
+    def __get_pcpr_from_name(name: str, reporter: RenameErrorReporter | None) -> BallanceObjectInfo | None:
+        regex_result = VirtoolsGroupConvention.cRegexPC.match(name)
+        if regex_result is not None:
+            return BallanceObjectInfo.create_from_checkpoint(
+                int(regex_result.group(1))
+            )
+        regex_result = VirtoolsGroupConvention.cRegexPR.match(name)
+        if regex_result is not None:
+            return BallanceObjectInfo.create_from_resetpoint(
+                int(regex_result.group(1))
+            )
+        
+        tr_text: str = bpy.app.translations.pgettext_rpt(
+            "PC_Checkpoints or PR_Resetpoints detected. But couldn't get sector from name.", 'BBP/UTIL_naming_convension.VirtoolsGroupConvention')
+        if reporter: reporter.add_error(tr_text)
+        return None
+    
+    @staticmethod
+    def __get_sector_from_groups(gps: typing.Iterator[str]) -> int | None:
+        # this counter is served for stupid 
+        # multi-sector-grouping accident.
+        counter: int = 0
+        last_matched_sector: int = 0
+        for i in gps:
+            regex_result: int | None = extract_sector_from_name(i)
+            if regex_result is not None:
+                last_matched_sector = regex_result
+                counter += 1
+                
+        if counter != 1: return None
+        else: return last_matched_sector
+
+    @staticmethod
+    def parse_from_object(obj: bpy.types.Object, reporter: RenameErrorReporter | None) -> BallanceObjectInfo | None:
+        # declare translation string type
+        tr_text: str
+
+        # create visitor
+        with PROP_virtools_group.VirtoolsGroupsHelper(obj) as gp:
+            # if no group, we should consider it is decoration or skylayer
+            if gp.get_count() == 0:
+                if obj.name == 'SkyLayer': return BallanceObjectInfo.create_from_others(BallanceObjectType.SKYLAYER)
+                else: return BallanceObjectInfo.create_from_others(BallanceObjectType.DECORATION)
+
+            # try to filter unique elements first
+            inter_gps: set[str] = gp.intersect_groups(_g_BlcUniqueComponents)
+            if len(inter_gps) == 1:
+                # get it
+                match((tuple(inter_gps))[0]):
+                    case 'PS_Levelstart':
+                        return BallanceObjectInfo.create_from_others(BallanceObjectType.LEVEL_START)
+                    case 'PE_Levelende':
+                        return BallanceObjectInfo.create_from_others(BallanceObjectType.LEVEL_END)
+                    case 'PC_Checkpoints' | 'PR_Resetpoints':
+                        # these type's data should be gotten from its name
+                        return VirtoolsGroupConvention.__get_pcpr_from_name(obj.name, reporter)
+                    case _:
+                        tr_text = bpy.app.translations.pgettext_rpt(
+                            "The match of Unique Component lost.", 'BBP/UTIL_naming_convension.VirtoolsGroupConvention')
+                        if reporter: reporter.add_error(tr_text)
+                        return None
+            elif len(inter_gps) != 0:
+                tr_text = bpy.app.translations.pgettext_rpt(
+                    "A Multi-grouping Unique Component.", 'BBP/UTIL_naming_convension.VirtoolsGroupConvention')
+                if reporter: reporter.add_error(tr_text)
+                return None
+            
+            # distinguish normal elements
+            inter_gps = gp.intersect_groups(_g_BlcNormalComponents)
+            if len(inter_gps) == 1:
+                # get it
+                # now try get its sector
+                gotten_elements: str = (tuple(inter_gps))[0]
+                gotten_sector: int | None = VirtoolsGroupConvention.__get_sector_from_groups(gp.iterate_groups())
+                if gotten_sector is None:
+                    # fail to get sector
+                    tr_text = bpy.app.translations.pgettext_rpt(
+                        "Component detected. But couldn't get sector from CKGroup data.", 'BBP/UTIL_naming_convension.VirtoolsGroupConvention')
+                    if reporter: reporter.add_error(tr_text)
+                    return None
+                return BallanceObjectInfo.create_from_component(
+                    gotten_elements,
+                    gotten_sector
+                )
+            elif len(inter_gps) != 0:
+                # must be a weird grouping, report it
+                tr_text = bpy.app.translations.pgettext_rpt(
+                    "A Multi-grouping Component.", 'BBP/UTIL_naming_convension.VirtoolsGroupConvention')
+                if reporter: reporter.add_error(tr_text)
+                return None
+
+            # distinguish road
+            if gp.contain_group('Phys_FloorRails'):
+                # rail
+                return BallanceObjectInfo.create_from_others(BallanceObjectType.RAIL)
+            elif gp.contain_group('Phys_Floors'):
+                # distinguish it between Floor and Wood
+                floor_result = gp.intersect_groups(_g_BlcFloor)
+                rail_result = gp.intersect_groups(_g_BlcWood)
+                if len(floor_result) > 0 and len(rail_result) == 0:
+                    return BallanceObjectInfo.create_from_others(BallanceObjectType.FLOOR)
+                elif len(floor_result) == 0 and len(rail_result) > 0:
+                    return BallanceObjectInfo.create_from_others(BallanceObjectType.WOOD)
+                else:
+                    tr_text = bpy.app.translations.pgettext_rpt(
+                        "Can't distinguish object between Floors and Rails. Suppose it is Floors.", 'BBP/UTIL_naming_convension.VirtoolsGroupConvention')
+                    if reporter: reporter.add_warning(tr_text)
+                    return BallanceObjectInfo.create_from_others(BallanceObjectType.FLOOR)
+            elif gp.contain_group('Phys_FloorStopper'):
+                return BallanceObjectInfo.create_from_others(BallanceObjectType.STOPPER)
+            elif gp.contain_group('DepthTestCubes'):
+                return BallanceObjectInfo.create_from_others(BallanceObjectType.DEPTH_CUBE)
+
+            # no matched
+            tr_text = bpy.app.translations.pgettext_rpt(
+                "Group match lost.", 'BBP/UTIL_naming_convension.VirtoolsGroupConvention')
+            if reporter: reporter.add_error(tr_text)
+            return None
+
+    @staticmethod
+    def set_to_object(obj: bpy.types.Object, info: BallanceObjectInfo, reporter: RenameErrorReporter | None) -> bool:
+        # create visitor
+        with PROP_virtools_group.VirtoolsGroupsHelper(obj) as gp:
+            # match by basic type
+            match(info.mBasicType):
+                case BallanceObjectType.DECORATION: pass    # decoration do not need group
+                case BallanceObjectType.SKYLAYER: pass  # sky layer do not need group
+                
+                case BallanceObjectType.LEVEL_START:
+                    gp.add_group('PS_Levelstart')
+                case BallanceObjectType.LEVEL_END:
+                    gp.add_group('PE_Levelende')
+                case BallanceObjectType.CHECKPOINT:
+                    gp.add_group('PC_Checkpoints')
+                case BallanceObjectType.RESETPOINT:
+                    gp.add_group('PR_Resetpoints')
+
+                case BallanceObjectType.DEPTH_CUBE:
+                    gp.add_group('PE_Levelende')
+
+                case BallanceObjectType.FLOOR:
+                    gp.add_group('Phys_Floors')
+                    gp.add_group('Sound_HitID_01')
+                    gp.add_group('Sound_RollID_01')
+                    # floor type also need group into shadow group.
+                    gp.add_group('Shadow')
+                case BallanceObjectType.RAIL:
+                    gp.add_group('Phys_FloorRails')
+                    gp.add_group('Sound_HitID_03')
+                    gp.add_group('Sound_RollID_03')
+                case BallanceObjectType.WOOD:
+                    gp.add_group('Phys_Floors')
+                    gp.add_group('Sound_HitID_02')
+                    gp.add_group('Sound_RollID_02')
+                case BallanceObjectType.STOPPER:
+                    gp.add_group('Phys_FloorStopper')
+
+                case BallanceObjectType.COMPONENT:
+                    # group into component type
+                    # use typing.cast() to force linter accept it because None is impossible
+                    gp.add_group(typing.cast(str, info.mComponentType))
+                    # group to sector
+                    gp.add_group(build_name_from_sector_index(typing.cast(int, info.mSector)))
+
+                case _:
+                    tr_text: str = bpy.app.translations.pgettext_rpt(
+                        "No matched info.", 'BBP/UTIL_naming_convension.VirtoolsGroupConvention')
+                    if reporter: reporter.add_error(tr_text)
+                    return False
+                
+        return True
+
+class YYCToolchainConvention():
+    @staticmethod
+    def parse_from_name(name: str, reporter: RenameErrorReporter | None) -> BallanceObjectInfo | None:
+        # check component first
+        regex_result = VirtoolsGroupConvention.cRegexComponent.match(name)  # use vt one because they are same
+        if regex_result is not None:
+            return BallanceObjectInfo.create_from_component(
+                regex_result.group(1),
+                int(regex_result.group(2))
+            )
+
+        # check PC PR elements
+        regex_result = VirtoolsGroupConvention.cRegexPC.match(name) # use vt one because they are same
+        if regex_result is not None:
+            return BallanceObjectInfo.create_from_checkpoint(
+                int(regex_result.group(1))
+            )
+        regex_result = VirtoolsGroupConvention.cRegexPR.match(name) # use vt one because they are same
+        if regex_result is not None:
+            return BallanceObjectInfo.create_from_resetpoint(
+                int(regex_result.group(1))
+            )
+
+        # check other unique elements
+        if name == "PS_FourFlames_01":
+            return BallanceObjectInfo.create_from_others(BallanceObjectType.LEVEL_START)
+        if name == "PE_Balloon_01":
+            return BallanceObjectInfo.create_from_others(BallanceObjectType.LEVEL_END)
+
+        # process floors
+        if name.startswith("A_Floor"):
+            return BallanceObjectInfo.create_from_others(BallanceObjectType.FLOOR)
+        if name.startswith("A_Rail"):
+            return BallanceObjectInfo.create_from_others(BallanceObjectType.RAIL)
+        if name.startswith("A_Wood"):
+            return BallanceObjectInfo.create_from_others(BallanceObjectType.WOOD)
+        if name.startswith("A_Stopper"):
+            return BallanceObjectInfo.create_from_others(BallanceObjectType.STOPPER)
+
+        # process others
+        if name.startswith("DepthCubes"):
+            return BallanceObjectInfo.create_from_others(BallanceObjectType.DEPTH_CUBE)
+        if name.startswith("D_"):
+            return BallanceObjectInfo.create_from_others(BallanceObjectType.DECORATION)
+        if name == 'SkyLayer':
+            return BallanceObjectInfo.create_from_others(BallanceObjectType.SKYLAYER)
+
+        tr_text: str = bpy.app.translations.pgettext_rpt(
+            "Name match lost.", 'BBP/UTIL_naming_convension.YYCToolchainConvention')
+        if reporter: reporter.add_error(tr_text)
+        return None
+
+
+    @staticmethod
+    def parse_from_object(obj: bpy.types.Object, reporter: RenameErrorReporter | None) -> BallanceObjectInfo | None:
+        return YYCToolchainConvention.parse_from_name(obj.name, reporter)
+        
+    @staticmethod
+    def set_to_name(info: BallanceObjectInfo, reporter: RenameErrorReporter | None) -> str | None:
+        match(info.mBasicType):
+            case BallanceObjectType.DECORATION:
+                return 'D_'
+            case BallanceObjectType.SKYLAYER:
+                return 'SkyLayer'
+            
+            case BallanceObjectType.LEVEL_START:
+                return 'PS_FourFlames_01'
+            case BallanceObjectType.LEVEL_END:
+                return 'PE_Balloon_01'
+            case BallanceObjectType.CHECKPOINT:
+                return f'PC_TwoFlames_{info.mSector:0>2d}'
+            case BallanceObjectType.RESETPOINT:
+                return f'PR_Resetpoint_{info.mSector:0>2d}'
+
+            case BallanceObjectType.DEPTH_CUBE:
+                return 'DepthCubes_'
+
+            case BallanceObjectType.FLOOR:
+                return 'A_Floor_'
+            case BallanceObjectType.RAIL:
+                return 'A_Rail_'
+            case BallanceObjectType.WOOD:
+                return 'A_Wood_'
+            case BallanceObjectType.STOPPER:
+                return 'A_Stopper_'
+
+            case BallanceObjectType.COMPONENT:
+                return '{}_{:0>2d}_'.format(
+                    info.mComponentType, info.mSector)
+                
+            case _:
+                tr_text: str = bpy.app.translations.pgettext_rpt(
+                    "No matched info.", 'BBP/UTIL_naming_convension.YYCToolchainConvention')
+                if reporter: reporter.add_error(tr_text)
+                return None
+            
+    @staticmethod
+    def set_to_object(obj: bpy.types.Object, info: BallanceObjectInfo, reporter: RenameErrorReporter | None) -> bool:
+        expect_name: str | None = YYCToolchainConvention.set_to_name(info, reporter)
+        if expect_name is None: return False
+
+        obj.name = expect_name
+        return True
+
+class ImengyuConvention():
+    cRegexComponent: typing.ClassVar[re.Pattern] = re.compile('^(' + '|'.join(_g_BlcNormalComponents) + '):[^:]*:([1-9]|[1-9][0-9])$')
+    cRegexPC: typing.ClassVar[re.Pattern] = re.compile('^PC_CheckPoint:([0-9]+)$')
+    cRegexPR: typing.ClassVar[re.Pattern] = re.compile('^PR_ResetPoint:([0-9]+)$')
+
+    @staticmethod
+    def parse_from_name(name: str, reporter: RenameErrorReporter | None) -> BallanceObjectInfo | None:
+        # check component first
+        regex_result = ImengyuConvention.cRegexComponent.match(name)
+        if regex_result is not None:
+            return BallanceObjectInfo.create_from_component(
+                regex_result.group(1),
+                int(regex_result.group(2))
+            )
+
+        # check PC PR elements
+        regex_result = ImengyuConvention.cRegexPC.match(name)
+        if regex_result is not None:
+            return BallanceObjectInfo.create_from_checkpoint(
+                int(regex_result.group(1))
+            )
+        regex_result = ImengyuConvention.cRegexPR.match(name)
+        if regex_result is not None:
+            return BallanceObjectInfo.create_from_resetpoint(
+                int(regex_result.group(1))
+            )
+
+        # check other unique elements
+        if name == "PS_LevelStart":
+            return BallanceObjectInfo.create_from_others(BallanceObjectType.LEVEL_START)
+        if name == "PE_LevelEnd":
+            return BallanceObjectInfo.create_from_others(BallanceObjectType.LEVEL_END)
+
+        # process floors
+        if name.startswith("S_Floors"):
+            return BallanceObjectInfo.create_from_others(BallanceObjectType.FLOOR)
+        if name.startswith("S_FloorRails"):
+            return BallanceObjectInfo.create_from_others(BallanceObjectType.RAIL)
+        if name.startswith("S_FloorWoods"):
+            return BallanceObjectInfo.create_from_others(BallanceObjectType.WOOD)
+        if name.startswith("S_FloorStopper"):
+            return BallanceObjectInfo.create_from_others(BallanceObjectType.STOPPER)
+
+        # process others
+        if name.startswith("DepthTestCubes"):
+            return BallanceObjectInfo.create_from_others(BallanceObjectType.DEPTH_CUBE)
+        if name.startswith("O_"):
+            return BallanceObjectInfo.create_from_others(BallanceObjectType.DECORATION)
+        if name == 'SkyLayer':
+            return BallanceObjectInfo.create_from_others(BallanceObjectType.SKYLAYER)
+
+        tr_text: str = bpy.app.translations.pgettext_rpt(
+            "Name match lost.", 'BBP/UTIL_naming_convension.ImengyuConvention')
+        if reporter: reporter.add_error(tr_text)
+        return None
+
+    @staticmethod
+    def parse_from_object(obj: bpy.types.Object, reporter: RenameErrorReporter | None) -> BallanceObjectInfo | None:
+        return ImengyuConvention.parse_from_name(obj.name, reporter)
+
+    @staticmethod
+    def set_to_name(info: BallanceObjectInfo, oldname: str | None, reporter: RenameErrorReporter | None) -> str | None:
+        match(info.mBasicType):
+            case BallanceObjectType.DECORATION:
+                return 'O_'
+            case BallanceObjectType.SKYLAYER:
+                return 'SkyLayer'
+            
+            case BallanceObjectType.LEVEL_START:
+                return 'PS_LevelStart'
+            case BallanceObjectType.LEVEL_END:
+                return 'PE_LevelEnd'
+            case BallanceObjectType.CHECKPOINT:
+                return f'PR_ResetPoint:{info.mSector:d}'
+            case BallanceObjectType.RESETPOINT:
+                return f'PC_CheckPoint:{info.mSector:d}'
+
+            case BallanceObjectType.DEPTH_CUBE:
+                return 'DepthTestCubes'
+
+            case BallanceObjectType.FLOOR:
+                return 'S_Floors'
+            case BallanceObjectType.RAIL:
+                return 'S_FloorWoods'
+            case BallanceObjectType.WOOD:
+                return 'S_FloorRails'
+            case BallanceObjectType.STOPPER:
+                return 'S_FloorStopper'
+
+            case BallanceObjectType.COMPONENT:
+                return '{}:{}:{:d}'.format(
+                    info.mComponentType, 
+                    oldname.replace(':', '_') if oldname is not None else '', 
+                    info.mSector
+                )
+                
+            case _:
+                tr_text: str = bpy.app.translations.pgettext_rpt(
+                    "No matched info.", 'BBP/UTIL_naming_convension.ImengyuConvention')
+                if reporter: reporter.add_error(tr_text)
+                return None
+            
+    @staticmethod
+    def set_to_object(obj: bpy.types.Object, info: BallanceObjectInfo, reporter: RenameErrorReporter | None) -> bool:
+        expect_name: str | None = ImengyuConvention.set_to_name(info, obj.name, reporter)
+        if expect_name is None: return False
+
+        obj.name = expect_name
+        return True
+
+
+#endregion

bbp_ng/UTIL_rail_creator.py

@@ -0,0 +1,347 @@
+import bpy, bmesh, mathutils, math
+import typing
+from . import UTIL_functions, UTIL_naming_convension
+from . import PROP_bme_material
+
+#region BMesh Operations Helper
+
+def _bmesh_extrude(
+        bm: bmesh.types.BMesh, 
+        start_edges: list[bmesh.types.BMEdge], 
+        direction: mathutils.Vector) -> list[bmesh.types.BMEdge]:
+    # extrude
+    ret: dict[str, typing.Any] = bmesh.ops.extrude_edge_only(
+        bm,
+        edges = start_edges, 
+        use_normal_flip = True, # NOTE: flip normal according to test result.
+        use_select_history = False
+    )
+
+    # get end edges
+    ret_geom = ret['geom']
+    del ret
+    end_verts: list[bmesh.types.BMVert] = list(filter(lambda x: isinstance(x, bmesh.types.BMVert), ret_geom))
+    end_edges: list[bmesh.types.BMEdge] = list(filter(lambda x: isinstance(x, bmesh.types.BMEdge) and x.is_boundary, ret_geom))
+    # and move it
+    bmesh.ops.translate(
+        bm,
+        vec = direction, space = mathutils.Matrix.Identity(4),
+        verts = end_verts,
+        use_shapekey = False
+    )
+
+    # return value
+    return end_edges
+
+def _bmesh_screw(
+        bm: bmesh.types.BMesh,
+        start_verts: list[bmesh.types.BMVert], start_edges: list[bmesh.types.BMEdge],
+        angle: float, steps: int, iterations: int,
+        center: mathutils.Vector, screw_per_iteration: float) -> list[bmesh.types.BMEdge]:
+    """
+    Hints: Angle is input as degree unit.
+    """
+    # screw
+    ret: dict[str, typing.Any] = bmesh.ops.spin(
+        bm,
+        geom = start_edges,
+        cent = center, 
+        axis = mathutils.Vector((0, 0, 1)), # default to +Z
+        dvec = mathutils.Vector((0, 0, screw_per_iteration / steps)), # conv to step delta
+        angle = math.radians(angle) * iterations,
+        space = mathutils.Matrix.Identity(4),
+        steps = steps * iterations,
+        use_merge = False,
+        use_normal_flip = True, # NOTE: flip normal according to test result.
+        use_duplicate = False
+    )
+
+    # return last segment
+    geom_last = ret['geom_last']
+    del ret
+    return list(filter(lambda x: isinstance(x, bmesh.types.BMEdge), geom_last))
+
+def _bmesh_cap(bm: bmesh.types.BMesh, edges: list[bmesh.types.BMEdge]) -> None:
+    """
+    Cap given edges. And mark it as sharp edge.
+    Please reset all edges to smooth one before calling this.
+    """
+    # fill holes
+    bmesh.ops.triangle_fill(
+        bm,
+        use_beauty = False, use_dissolve = False,
+        edges = edges
+        # no pass to normal.
+    )
+    
+    # and only set sharp for cap's edges
+    for edge in edges:
+        edge.smooth = False
+
+def _bmesh_smooth_all_edges(bm: bmesh.types.BMesh) -> None:
+    """
+    Reset all edges to smooth. Call this before calling edge cap function.
+    """
+    # reset all edges to smooth
+    edge: bmesh.types.BMEdge
+    for edge in bm.edges:
+        edge.smooth = True
+
+def _bmesh_flip_all_faces(bm: bmesh.types.BMesh, flip_x: bool, flip_y: bool, flip_z: bool) -> None:
+    """
+    Flip the whole geometry in given bmesh with given axis.
+    """
+    # get mirror result
+    scale_factor: mathutils.Vector = mathutils.Vector((
+        (-1 if flip_x else 1),
+        (-1 if flip_y else 1),
+        (-1 if flip_z else 1)
+    ))
+    bmesh.ops.scale(bm, vec = scale_factor, verts = bm.verts[:])
+
+    # check whether we need perform normal flip.
+    # see UTIL_bme._is_mirror_matrix for more detail
+    test_matrix: mathutils.Matrix = mathutils.Matrix.LocRotScale(None, None, scale_factor)
+    if test_matrix.is_negative:
+        bmesh.ops.reverse_faces(bm, faces = bm.faces[:])
+
+#endregion
+
+#region Real Rail Creators
+
+def rail_creator_wrapper(fct_poly_cret: typing.Callable[[bmesh.types.BMesh], None], extra_transform: mathutils.Matrix) -> bpy.types.Object:
+    # create mesh first
+    bm: bmesh.types.BMesh = bmesh.new()
+
+    # call cret fct
+    fct_poly_cret(bm)
+
+    # finish up
+    mesh: bpy.types.Mesh = bpy.data.meshes.new('Rail')
+    bm.to_mesh(mesh)
+    bm.free()
+    
+    # setup smooth for mesh
+    mesh.shade_smooth()
+
+    # setup default material
+    with PROP_bme_material.BMEMaterialsHelper(bpy.context.scene) as bmemtl:
+        mesh.materials.clear()
+        mesh.materials.append(bmemtl.get_material('Rail'))
+        mesh.validate_material_indices()
+
+    # create object and assoc with it
+    # create info first
+    rail_info: UTIL_naming_convension.BallanceObjectInfo = UTIL_naming_convension.BallanceObjectInfo.create_from_others(
+        UTIL_naming_convension.BallanceObjectType.RAIL
+    )
+    # then get object name
+    rail_name: str | None = UTIL_naming_convension.YYCToolchainConvention.set_to_name(rail_info, None)
+    if rail_name is None: raise UTIL_functions.BBPException('impossible null name')
+    # create object by name
+    obj: bpy.types.Object = bpy.data.objects.new(rail_name, mesh)
+    # assign virtools groups
+    UTIL_naming_convension.VirtoolsGroupConvention.set_to_object(obj, rail_info, None)
+
+    # move to cursor
+    UTIL_functions.add_into_scene_and_move_to_cursor(obj)
+    # add extra transform
+    obj.matrix_world = obj.matrix_world @ extra_transform
+    # select created object
+    UTIL_functions.select_certain_objects((obj, ))
+    
+    # return rail
+    return obj
+
+def create_rail_section(
+        bm: bmesh.types.BMesh,
+        is_monorail: bool, rail_radius: float, rail_span: float, 
+        matrix: mathutils.Matrix = mathutils.Matrix.Identity(4)) -> None:
+    """
+    Add a rail section.
+
+    If created is monorail, the original point locate at the center of section.
+    Otherwise, the original point locate at the center point of the line connecting between left rail section and right rail section.
+    The section will be placed in XZ panel.
+
+    If ordered is monorail, `rail_span` param will be ignored.
+    """
+    if is_monorail:
+        # create monorail
+        bmesh.ops.create_circle(
+            bm, cap_ends = False, cap_tris = False, segments = 8, radius = rail_radius,
+            matrix = typing.cast(mathutils.Matrix, matrix @ mathutils.Matrix.LocRotScale(
+                None,
+                mathutils.Euler((math.radians(90), math.radians(22.5), 0), 'XYZ'),
+                None
+            )), 
+            calc_uvs = False
+        )
+    else:
+        # create rail
+        # create left rail
+        bmesh.ops.create_circle(
+            bm, cap_ends = False, cap_tris = False, segments = 8, radius = rail_radius,
+            matrix = typing.cast(mathutils.Matrix, matrix @ mathutils.Matrix.LocRotScale(
+                mathutils.Vector((-rail_span / 2, 0, 0)), 
+                mathutils.Euler((math.radians(90), 0, 0), 'XYZ'),
+                None
+            )),
+            calc_uvs = False
+        )
+        # create right rail
+        bmesh.ops.create_circle(
+            bm, cap_ends = False, cap_tris = False, segments = 8, radius = rail_radius,
+            matrix = typing.cast(mathutils.Matrix, matrix @ mathutils.Matrix.LocRotScale(
+                mathutils.Vector((rail_span / 2, 0, 0)), 
+                mathutils.Euler((math.radians(90), 0, 0), 'XYZ'),
+                None
+            )),
+            calc_uvs = False
+        )
+
+def create_transition_section(
+        bm: bmesh.types.BMesh,
+        rail_radius: float, rail_span: float) -> None:
+    """
+    Create the transition section between rail and monorail.
+    """
+    # create rail section
+    create_rail_section(bm, False, rail_radius, rail_span)
+
+    # create monorail
+    # calc sink first
+    monorail_sink: float
+    try:
+        monorail_sink = math.sqrt((rail_radius + 2) ** 2 - (rail_span / 2) ** 2) - 2 - rail_radius
+    except:
+        monorail_sink = -2 # if sqrt(minus number) happended, it mean no triangle relation. the depth should always be -2.
+    # create monorail with calculated sink
+    create_rail_section(
+        bm, True, rail_radius, rail_span,
+        mathutils.Matrix.Translation((0, 0, monorail_sink))
+    )
+
+def create_straight_rail(
+        bm: bmesh.types.BMesh,
+        is_monorail: bool, rail_radius: float, rail_span: float,
+        rail_length: float, rail_angle: float,
+        rail_start_cap: bool, rail_end_cap: bool) -> None:
+    """
+    Add a straight rail.
+
+    The original point is same as `_add_rail_section()`.
+    The start terminal of this straight will be placed in XZ panel.
+    The expand direction is +Y.
+
+    If ordered is monorail, `rail_span` param will be ignored.
+
+    The rail angle is in degree unit and indicate how any angle this rail should rotated by its axis.
+    It usually used to create side rail.
+    """
+    # create section first
+    create_rail_section(
+        bm, is_monorail, rail_radius, rail_span,
+        mathutils.Matrix.LocRotScale(
+            None,
+            mathutils.Euler((0, math.radians(rail_angle), 0), 'XYZ'),
+            None
+        )
+    )
+
+    # get start edges
+    start_edges: list[bmesh.types.BMEdge] = bm.edges[:]
+    # extrude and get end edges
+    end_edges: list[bmesh.types.BMEdge] = _bmesh_extrude(
+        bm, 
+        start_edges, 
+        mathutils.Vector((0, rail_length, 0))
+    )
+
+    # smooth geometry
+    _bmesh_smooth_all_edges(bm)
+
+    # cap start and end edges if needed
+    if rail_start_cap:
+        _bmesh_cap(bm, start_edges)
+    if rail_end_cap:
+        _bmesh_cap(bm, end_edges)
+
+def create_transition_rail(
+        bm: bmesh.types.BMesh,
+        rail_radius: float, rail_span: float,
+        rail_length: float,
+        rail_start_cap: bool, rail_end_cap: bool) -> None:
+    """
+    Add a transition rail.
+
+    The original point is same as `_add_transition_section()`.
+    The start terminal of this straight will be placed in XZ panel.
+    The expand direction is +Y.
+    """
+    # create section first
+    create_transition_section(bm, rail_radius, rail_span)
+
+    # get start edges
+    start_edges: list[bmesh.types.BMEdge] = bm.edges[:]
+    # extrude and get end edges
+    end_edges: list[bmesh.types.BMEdge] = _bmesh_extrude(
+        bm, 
+        start_edges, 
+        mathutils.Vector((0, rail_length, 0))
+    )
+
+    # smooth geometry
+    _bmesh_smooth_all_edges(bm)
+
+    # cap start and end edges if needed
+    if rail_start_cap:
+        _bmesh_cap(bm, start_edges)
+    if rail_end_cap:
+        _bmesh_cap(bm, end_edges)
+
+def create_screw_rail(
+        bm: bmesh.types.BMesh, 
+        is_monorail: bool, rail_radius: float, rail_span: float,
+        rail_start_cap: bool, rail_end_cap: bool,
+        rail_screw_angle: float, rail_screw_screw: float, rail_screw_iterations: int,
+        rail_screw_steps: int, rail_screw_radius: float,
+        rail_screw_flip_x: bool, rail_screw_flip_y: bool, rail_screw_flip_z: bool) -> None:
+    """
+    Add a screw rail.
+
+    The original point is same as `_add_rail_section()`.
+    The start terminal of this straight will be placed in XZ panel.
+    The expand direction is +Y.
+
+    If ordered is monorail, `rail_span` param will be ignored.
+
+    Angle is input as degree unit.
+    """
+    # create section first
+    create_rail_section(bm, is_monorail, rail_radius, rail_span)
+
+    start_edges: list[bmesh.types.BMEdge] = bm.edges[:]
+    end_edges: list[bmesh.types.BMEdge] = _bmesh_screw(
+        bm,
+        bm.verts[:], start_edges,
+        rail_screw_angle, 
+        rail_screw_steps, rail_screw_iterations,
+        mathutils.Vector((rail_screw_radius, 0, 0)),
+        rail_screw_screw
+    )
+
+    # flip geometry
+    if rail_screw_flip_x or rail_screw_flip_y or rail_screw_flip_z:
+        _bmesh_flip_all_faces(bm, rail_screw_flip_x, rail_screw_flip_y, rail_screw_flip_z)
+
+    # smooth geometry
+    _bmesh_smooth_all_edges(bm)
+
+    # cap start and end edges if needed
+    if rail_start_cap:
+        _bmesh_cap(bm, start_edges)
+    if rail_end_cap:
+        _bmesh_cap(bm, end_edges)
+
+#endregion

bbp_ng/UTIL_translation.py

@@ -0,0 +1,99 @@
+import bpy
+
+#region Translation Contexts
+
+## NOTE: Translation Priniciple
+#  Due to the shitty design of Blender I18N tools (I can't specify context for every translation entries and its static analyse is so bad),
+#  I will specify all context but I can't do anything if Blender throw my translation context away.
+#  
+#  BME module has its own context naming convention which make sure all configuration fields of prototypes are properly translated.
+#  This module also provide a corresponding function to compute these context string from given BME prototype name and the index of configuration fields.
+#  
+#  For BBP plugin self, there is a list containing multiple priniciples which you should follow when providing translation context.
+#  - For operator, menu, panel and etc.
+#      * For themselves, fill `bl_translation_context` to their name, such as `BBP_OT_some_operator`.
+#      * For properties located inside, add `/property` suffix, such as `BBP_OT_some_operator/property`.
+#      * For draw function (any function callings requiring translation context inside it), add `/draw` suffix, such as `BBP_OT_some_operator/draw`.
+#      * For execute function, or any functions mainly called by this execution function, add `/execute` suffix, such as `BBP_OT_some_operator/execute`.
+#  - For shared class (usually shared by multiple operators).
+#      * For themselves (usually not used because they don't have `bl_translation_context`), the default context is `BME/<MODULE_NAME>.<CLASS_NAME>`, such as `BBP/some_module.some_class`.
+#      * For properties located inside, add `/property` suffix, such as `BBP/some_module.some_class/property`.
+#      * For draw function (any function callings requiring translation context inside it), add `/draw` suffix, such as `BBP/some_module.some_class/draw`.
+#  - For menu draw function (usually defined in __init__ module).
+#      * For themselves (any calling inside them), the context is `BME/<MODULE_NAME>.<METHOD_NAME>()`, such as `BBP/some_module.some_method()`.
+#  
+#  Due to the shitty design, I can't find a way to add translation context for descrption field and report function used string.
+#  So these description may collide with Blender official translation, thus they may not be put in result translation file.
+#  I have no idea about this.
+#  
+#  Due to the shitty static analyse ability of Blender I18N plugin, all context should be written in literal,
+#  not the reference to other fields or the return value of some function.
+#  However for those strings, which originally should not be extracted by Blender I18N plugin, the way to get their context string is free.
+#  
+#  
+#  For the string given to Python `print()` which will be output in console,
+#  please use `bpy.app.translations.pgettext_rpt()` to get translation message because they are report.
+#  For the string given to `UTIL_functions.message_box()`, please use `bpy.app.translations.pgettext_iface` because they are UI elements.
+#  
+#  `bpy.app.translations.pgettext` function family has fatal error when extracting message with context
+#  (it will produce a correct one and a wrong one which just simply concat the message and its context. I don't know why).
+#  This will happen if you put `bpy.app.translations.pgettext` calling inside `UILayout.label` or any UILayout functions like it.
+#  `bpy.app.translations.pgettext` will produce the correct entry but Blender used "magic of `UILayout.label` will produce the wrong one.
+#  It seems that Blender's magic just join the string provided in `text` argument as much as possible.
+#  So the solution is simple:
+#  - If we use `bpy.app.translations.pgettext` and `UILayout.label` together
+#      * Create a variable holding the result of `bpy.app.translations.pgettext`.
+#      * Format this gotten string if necessary.
+#      * Call `UILayout.label` and use this variable as its `text` argument. Then set `translated` to False.
+#  - If we use `bpy.app.translations.pgettext` with other non-Blender functions, such as `print`.
+#      * Use it as a normal function.
+#  
+#  All translation annotation are started with `TR:`
+#  
+
+# The universal translation context prefix for BBP_NG plugin.
+CTX_BBP: str = 'BBP'
+
+# The universal translation context prefix for BME module in BBP_NG plugin.
+CTX_BBP_BME: str = CTX_BBP + '/BME'
+def build_prototype_showcase_context(identifier: str) -> str:
+    """
+    Build the context for getting the translation for BME prototype showcase title.
+    @param[in] identifier The identifier of this prototype.
+    @return The context for getting translation.
+    """
+    return CTX_BBP_BME + '/' + identifier
+def build_prototype_showcase_cfg_context(identifier: str, cfg_index: int) -> str:
+    """
+    Build the context for getting the translation for BME prototype showcase configuration title or description.
+    @param[in] identifier The identifier of this prototype.
+    @param[in] cfg_index The index of this configuration in this prototype showcase.
+    @return The context for getting translation.
+    """
+    return CTX_BBP_BME + f'/{identifier}/[{cfg_index}]'
+
+#endregion
+
+# ##### BEGIN AUTOGENERATED I18N SECTION #####
+# NOTE: You can safely move around this auto-generated block (with the begin/end markers!),
+#       and edit the translations by hand.
+#       Just carefully respect the format of the tuple!
+
+# Tuple of tuples:
+# ((msgctxt, msgid), (sources, gen_comments), (lang, translation, (is_fuzzy, comments)), ...)
+translations_tuple = ()
+
+translations_dict = {}
+for msg in translations_tuple:
+    key = msg[0]
+    for lang, trans, (is_fuzzy, comments) in msg[2:]:
+        if trans and not is_fuzzy:
+            translations_dict.setdefault(lang, {})[key] = trans
+
+# ##### END AUTOGENERATED I18N SECTION #####
+
+def register() -> None:
+    bpy.app.translations.register(__package__, translations_dict)
+
+def unregister() -> None:
+    bpy.app.translations.unregister(__package__)

bbp_ng/UTIL_virtools_types.py

@@ -0,0 +1,278 @@
+import bpy, mathutils
+import typing, math
+from . import UTIL_functions
+
+# extract all declarations in PyBMap
+from .PyBMap.virtools_types import *
+# and add some patches for them
+# mainly patch them with functions exchanging data with blender
+# and the convertion between differnet coordinate system.
+# hint: `co` mean coordinate system in blender.
+
+#region VxVector2 Patch
+
+def vxvector2_conv_co(self: VxVector2) -> None:
+    """
+    Convert UV coordinate system between Virtools and Blender.
+    """
+    self.y = -self.y
+
+#endregion
+
+#region VxVector3 Patch
+
+def vxvector3_conv_co(self: VxVector3) -> None:
+    """
+    Convert Position or Normal coordinate system between Virtools and Blender.
+    """
+    self.y, self.z = self.z, self.y
+
+#endregion
+
+#region VxMatrix Patch
+
+def vxmatrix_conv_co(self: VxMatrix) -> None:
+    """
+    Convert World Matrix coordinate system between Virtools and Blender.
+    """
+    # swap column 1 and 2
+    for i in range(4):
+        self.data[i][1], self.data[i][2] = self.data[i][2], self.data[i][1]
+    # swap row 1 and 2
+    for i in range(4):
+        self.data[1][i], self.data[2][i] = self.data[2][i], self.data[1][i]
+
+def vxmatrix_from_blender(self: VxMatrix, data_: mathutils.Matrix) -> None:
+    """
+    Set matrix by blender matrix.
+    Please note there is no corrdinate system convertion between 
+    """
+    # transposed first
+    data: mathutils.Matrix = data_.transposed()
+    (
+        self.data[0][0], self.data[0][1], self.data[0][2], self.data[0][3],
+        self.data[1][0], self.data[1][1], self.data[1][2], self.data[1][3],
+        self.data[2][0], self.data[2][1], self.data[2][2], self.data[2][3],
+        self.data[3][0], self.data[3][1], self.data[3][2], self.data[3][3]
+    ) = (
+        data[0][0], data[0][1], data[0][2], data[0][3],
+        data[1][0], data[1][1], data[1][2], data[1][3],
+        data[2][0], data[2][1], data[2][2], data[2][3],
+        data[3][0], data[3][1], data[3][2], data[3][3]
+    )
+
+def vxmatrix_to_blender(self: VxMatrix) -> mathutils.Matrix:
+    """
+    Get blender matrix from this matrix
+    """
+    data: mathutils.Matrix = mathutils.Matrix((
+        (self.data[0][0], self.data[0][1], self.data[0][2], self.data[0][3]),
+        (self.data[1][0], self.data[1][1], self.data[1][2], self.data[1][3]),
+        (self.data[2][0], self.data[2][1], self.data[2][2], self.data[2][3]),
+        (self.data[3][0], self.data[3][1], self.data[3][2], self.data[3][3]),
+    ))
+    # transpose self
+    data.transpose()
+    return data
+
+## Hints about Light Matrix
+#  There is a slight difference between Virtools and Blender.
+#  In blender, the default direction of all directional light (spot and sun) are Down (-Z).
+#  Hoewver, in Virtools, the default direction of all directional light (spot and directional) are Forward (+Z).
+#  
+#  As brief view, in Blender coordinate system, you can see that we got Blender default light direction
+#  from Virtools default light direction by rotating it around X-axis with -90 degree
+#  (the positive rotation direction is decided by right hand priniciple).
+#  
+#  So, if the object we importing is a light, we need add a special transform matrix ahead of world matrix
+#  to correct the light default direction first.
+#  When exporting, just do a reverse operation.
+
+def bldmatrix_patch_light_obj(data: mathutils.Matrix) -> mathutils.Matrix:
+    """
+    Add patch for light world matrix to correct its direction.
+    This function is usually used when importing light.
+    """
+    # we multiple a matrix which represent a 90 degree roration in X-axis.
+    # right multiple means that it will apply to light first, before apply the matrix gotten from virtools.
+    return data @ mathutils.Matrix.Rotation(math.radians(90), 4, 'X')
+
+def bldmatrix_restore_light_obj(data: mathutils.Matrix) -> mathutils.Matrix:
+    """
+    The reverse operation of bldmatrix_patch_light_mat().
+    This function is usually used when exporting light.
+    """
+    # as the reverse operation, we need right mutiple a reversed matrix of the matrix
+    # which represent a 90 degree roration in X-axis to remove the matrix we added in patch step.
+    # however, the reverse matrix of 90 degree X-axis rotation is just NEGATUIVE 90 degree X-axis rotation.
+    # so we simply right multiple it.
+    return data @ mathutils.Matrix.Rotation(math.radians(-90), 4, 'X')
+
+#endregion
+
+#region Blender EnumProperty Creation
+
+class EnumAnnotation():
+    mDisplayName: str
+    mDescription: str
+    def __init__(self, display_name: str, description: str):
+        self.mDisplayName = display_name
+        self.mDescription = description
+
+_g_Annotation: dict[type, dict[int, EnumAnnotation]] = {
+    VXTEXTURE_BLENDMODE: {
+        VXTEXTURE_BLENDMODE.VXTEXTUREBLEND_DECAL.value: EnumAnnotation("Decal", "Texture replace any material information "),
+        VXTEXTURE_BLENDMODE.VXTEXTUREBLEND_MODULATE.value: EnumAnnotation("Modulate", "Texture and material are combine. Alpha information of the texture replace material alpha component. "),
+        VXTEXTURE_BLENDMODE.VXTEXTUREBLEND_DECALALPHA.value: EnumAnnotation("Decal Alpha", "Alpha information in the texture specify how material and texture are combined. Alpha information of the texture replace material alpha component. "),
+        VXTEXTURE_BLENDMODE.VXTEXTUREBLEND_MODULATEALPHA.value: EnumAnnotation("Modulate Alpha", "Alpha information in the texture specify how material and texture are combined "),
+        VXTEXTURE_BLENDMODE.VXTEXTUREBLEND_DECALMASK.value: EnumAnnotation("Decal Mask", ""),
+        VXTEXTURE_BLENDMODE.VXTEXTUREBLEND_MODULATEMASK.value: EnumAnnotation("Modulate Mask", ""),
+        VXTEXTURE_BLENDMODE.VXTEXTUREBLEND_COPY.value: EnumAnnotation("Copy", "Equivalent to DECAL "),
+        VXTEXTURE_BLENDMODE.VXTEXTUREBLEND_ADD.value: EnumAnnotation("Add", ""),
+        VXTEXTURE_BLENDMODE.VXTEXTUREBLEND_DOTPRODUCT3.value: EnumAnnotation("Dot Product 3", "Perform a Dot Product 3 between texture (normal map) and a referential vector given in VXRENDERSTATE_TEXTUREFACTOR. "),
+        VXTEXTURE_BLENDMODE.VXTEXTUREBLEND_MAX.value: EnumAnnotation("Max", ""),
+    },
+    VXTEXTURE_FILTERMODE: {
+        VXTEXTURE_FILTERMODE.VXTEXTUREFILTER_NEAREST.value: EnumAnnotation("Nearest", "No Filter "),
+        VXTEXTURE_FILTERMODE.VXTEXTUREFILTER_LINEAR.value: EnumAnnotation("Linear", "Bilinear Interpolation "),
+        VXTEXTURE_FILTERMODE.VXTEXTUREFILTER_MIPNEAREST.value: EnumAnnotation("Mip Nearest", "Mip mapping "),
+        VXTEXTURE_FILTERMODE.VXTEXTUREFILTER_MIPLINEAR.value: EnumAnnotation("Mip Linear", "Mip Mapping with Bilinear interpolation "),
+        VXTEXTURE_FILTERMODE.VXTEXTUREFILTER_LINEARMIPNEAREST.value: EnumAnnotation("Linear Mip Nearest", "Mip Mapping with Bilinear interpolation between mipmap levels. "),
+        VXTEXTURE_FILTERMODE.VXTEXTUREFILTER_LINEARMIPLINEAR.value: EnumAnnotation("Linear Mip Linear", "Trilinear Filtering "),
+        VXTEXTURE_FILTERMODE.VXTEXTUREFILTER_ANISOTROPIC.value: EnumAnnotation("Anisotropic", "Anisotropic filtering "),
+    },
+    VXBLEND_MODE: {
+        VXBLEND_MODE.VXBLEND_ZERO.value: EnumAnnotation("Zero", "Blend factor is (0, 0, 0, 0). "),
+        VXBLEND_MODE.VXBLEND_ONE.value: EnumAnnotation("One", "Blend factor is (1, 1, 1, 1). "),
+        VXBLEND_MODE.VXBLEND_SRCCOLOR.value: EnumAnnotation("Src Color", "Blend factor is (Rs, Gs, Bs, As). "),
+        VXBLEND_MODE.VXBLEND_INVSRCCOLOR.value: EnumAnnotation("Inv Src Color", "Blend factor is (1-Rs, 1-Gs, 1-Bs, 1-As). "),
+        VXBLEND_MODE.VXBLEND_SRCALPHA.value: EnumAnnotation("Src Alpha", "Blend factor is (As, As, As, As). "),
+        VXBLEND_MODE.VXBLEND_INVSRCALPHA.value: EnumAnnotation("Inv Src Alpha", "Blend factor is (1-As, 1-As, 1-As, 1-As). "),
+        VXBLEND_MODE.VXBLEND_DESTALPHA.value: EnumAnnotation("Dest Alpha", "Blend factor is (Ad, Ad, Ad, Ad). "),
+        VXBLEND_MODE.VXBLEND_INVDESTALPHA.value: EnumAnnotation("Inv Dest Alpha", "Blend factor is (1-Ad, 1-Ad, 1-Ad, 1-Ad). "),
+        VXBLEND_MODE.VXBLEND_DESTCOLOR.value: EnumAnnotation("Dest Color", "Blend factor is (Rd, Gd, Bd, Ad). "),
+        VXBLEND_MODE.VXBLEND_INVDESTCOLOR.value: EnumAnnotation("Inv Dest Color", "Blend factor is (1-Rd, 1-Gd, 1-Bd, 1-Ad). "),
+        VXBLEND_MODE.VXBLEND_SRCALPHASAT.value: EnumAnnotation("Src Alpha Sat", "Blend factor is (f, f, f, 1); f = min(As, 1-Ad). "),
+        #VXBLEND_MODE.VXBLEND_BOTHSRCALPHA.value: EnumAnnotation("Both Src Alpha", "Source blend factor is (As, As, As, As) and destination blend factor is (1-As, 1-As, 1-As, 1-As) "),
+        #VXBLEND_MODE.VXBLEND_BOTHINVSRCALPHA.value: EnumAnnotation("Both Inv Src Alpha", "Source blend factor is (1-As, 1-As, 1-As, 1-As) and destination blend factor is (As, As, As, As) "),
+    },
+    VXTEXTURE_ADDRESSMODE: {
+        VXTEXTURE_ADDRESSMODE.VXTEXTURE_ADDRESSWRAP.value: EnumAnnotation("Wrap", "Default mesh wrap mode is used (see CKMesh::SetWrapMode) "),
+        VXTEXTURE_ADDRESSMODE.VXTEXTURE_ADDRESSMIRROR.value: EnumAnnotation("Mirror", "Texture coordinates outside the range [0..1] are flipped evenly. "),
+        VXTEXTURE_ADDRESSMODE.VXTEXTURE_ADDRESSCLAMP.value: EnumAnnotation("Clamp", "Texture coordinates greater than 1.0 are set to 1.0, and values less than 0.0 are set to 0.0. "),
+        VXTEXTURE_ADDRESSMODE.VXTEXTURE_ADDRESSBORDER.value: EnumAnnotation("Border", "When texture coordinates are greater than 1.0 or less than 0.0  texture is set to a color defined in CKMaterial::SetTextureBorderColor. "),
+        VXTEXTURE_ADDRESSMODE.VXTEXTURE_ADDRESSMIRRORONCE.value: EnumAnnotation("Mirror Once", " "),
+    },
+    VXFILL_MODE: {
+        VXFILL_MODE.VXFILL_POINT.value: EnumAnnotation("Point", "Vertices rendering "),
+        VXFILL_MODE.VXFILL_WIREFRAME.value: EnumAnnotation("Wireframe", "Edges rendering "),
+        VXFILL_MODE.VXFILL_SOLID.value: EnumAnnotation("Solid", "Face rendering "),
+    },
+    VXSHADE_MODE: {
+        VXSHADE_MODE.VXSHADE_FLAT.value: EnumAnnotation("Flat", "Flat Shading "),
+        VXSHADE_MODE.VXSHADE_GOURAUD.value: EnumAnnotation("Gouraud", "Gouraud Shading "),
+        VXSHADE_MODE.VXSHADE_PHONG.value: EnumAnnotation("Phong", "Phong Shading (Not yet supported by most implementation) "),
+    },
+    VXCMPFUNC: {
+        VXCMPFUNC.VXCMP_NEVER.value: EnumAnnotation("Never", "Always fail the test. "),
+        VXCMPFUNC.VXCMP_LESS.value: EnumAnnotation("Less", "Accept if value if less than current value. "),
+        VXCMPFUNC.VXCMP_EQUAL.value: EnumAnnotation("Equal", "Accept if value if equal than current value. "),
+        VXCMPFUNC.VXCMP_LESSEQUAL.value: EnumAnnotation("Less Equal", "Accept if value if less or equal than current value. "),
+        VXCMPFUNC.VXCMP_GREATER.value: EnumAnnotation("Greater", "Accept if value if greater than current value. "),
+        VXCMPFUNC.VXCMP_NOTEQUAL.value: EnumAnnotation("Not Equal", "Accept if value if different than current value. "),
+        VXCMPFUNC.VXCMP_GREATEREQUAL.value: EnumAnnotation("Greater Equal", "Accept if value if greater or equal current value. "),
+        VXCMPFUNC.VXCMP_ALWAYS.value: EnumAnnotation("Always", "Always accept the test. "),
+    },
+    CK_TEXTURE_SAVEOPTIONS: {
+        CK_TEXTURE_SAVEOPTIONS.CKTEXTURE_RAWDATA.value: EnumAnnotation("Raw Data", "Save raw data inside file. The bitmap is saved in a raw 32 bit per pixel format. "),
+        CK_TEXTURE_SAVEOPTIONS.CKTEXTURE_EXTERNAL.value: EnumAnnotation("External", "Store only the file name for the texture. The bitmap file must be present in the bitmap paths when loading the composition. "),
+        CK_TEXTURE_SAVEOPTIONS.CKTEXTURE_IMAGEFORMAT.value: EnumAnnotation("Image Format", "Save using format specified. The bitmap data will be converted to the specified format by the correspondant bitmap plugin and saved inside file. "),
+        CK_TEXTURE_SAVEOPTIONS.CKTEXTURE_USEGLOBAL.value: EnumAnnotation("Use Global", "Use Global settings, that is the settings given with CKContext::SetGlobalImagesSaveOptions. (Not valid when using CKContext::SetImagesSaveOptions). "),
+        CK_TEXTURE_SAVEOPTIONS.CKTEXTURE_INCLUDEORIGINALFILE.value: EnumAnnotation("Include Original File", "Insert original image file inside CMO file. The bitmap file that was used originally for the texture or sprite will be append to the composition file and extracted when the file is loaded. "),
+    },
+    VX_PIXELFORMAT: {
+        VX_PIXELFORMAT._32_ARGB8888.value: EnumAnnotation("32 Bits ARGB8888", "32-bit ARGB pixel format with alpha "),
+        VX_PIXELFORMAT._32_RGB888.value: EnumAnnotation("32 Bits RGB888", "32-bit RGB pixel format without alpha "),
+        VX_PIXELFORMAT._24_RGB888.value: EnumAnnotation("24 Bits RGB888", "24-bit RGB pixel format "),
+        VX_PIXELFORMAT._16_RGB565.value: EnumAnnotation("16 Bits RGB565", "16-bit RGB pixel format "),
+        VX_PIXELFORMAT._16_RGB555.value: EnumAnnotation("16 Bits RGB555", "16-bit RGB pixel format (5 bits per color) "),
+        VX_PIXELFORMAT._16_ARGB1555.value: EnumAnnotation("16 Bits ARGB1555", "16-bit ARGB pixel format (5 bits per color + 1 bit for alpha) "),
+        VX_PIXELFORMAT._16_ARGB4444.value: EnumAnnotation("16 Bits ARGB4444", "16-bit ARGB pixel format (4 bits per color) "),
+        VX_PIXELFORMAT._8_RGB332.value: EnumAnnotation("8 Bits RGB332", "8-bit  RGB pixel format "),
+        VX_PIXELFORMAT._8_ARGB2222.value: EnumAnnotation("8 Bits ARGB2222", "8-bit  ARGB pixel format "),
+        VX_PIXELFORMAT._32_ABGR8888.value: EnumAnnotation("32 Bits ABGR8888", "32-bit ABGR pixel format "),
+        VX_PIXELFORMAT._32_RGBA8888.value: EnumAnnotation("32 Bits RGBA8888", "32-bit RGBA pixel format "),
+        VX_PIXELFORMAT._32_BGRA8888.value: EnumAnnotation("32 Bits BGRA8888", "32-bit BGRA pixel format "),
+        VX_PIXELFORMAT._32_BGR888.value: EnumAnnotation("32 Bits BGR888", "32-bit BGR pixel format "),
+        VX_PIXELFORMAT._24_BGR888.value: EnumAnnotation("24 Bits BGR888", "24-bit BGR pixel format "),
+        VX_PIXELFORMAT._16_BGR565.value: EnumAnnotation("16 Bits BGR565", "16-bit BGR pixel format "),
+        VX_PIXELFORMAT._16_BGR555.value: EnumAnnotation("16 Bits BGR555", "16-bit BGR pixel format (5 bits per color) "),
+        VX_PIXELFORMAT._16_ABGR1555.value: EnumAnnotation("16 Bits ABGR1555", "16-bit ABGR pixel format (5 bits per color + 1 bit for alpha) "),
+        VX_PIXELFORMAT._16_ABGR4444.value: EnumAnnotation("16 Bits ABGR4444", "16-bit ABGR pixel format (4 bits per color) "),
+        VX_PIXELFORMAT._DXT1.value: EnumAnnotation("DXT1", "S3/DirectX Texture Compression 1 "),
+        VX_PIXELFORMAT._DXT2.value: EnumAnnotation("DXT2", "S3/DirectX Texture Compression 2 "),
+        VX_PIXELFORMAT._DXT3.value: EnumAnnotation("DXT3", "S3/DirectX Texture Compression 3 "),
+        VX_PIXELFORMAT._DXT4.value: EnumAnnotation("DXT4", "S3/DirectX Texture Compression 4 "),
+        VX_PIXELFORMAT._DXT5.value: EnumAnnotation("DXT5", "S3/DirectX Texture Compression 5 "),
+        VX_PIXELFORMAT._16_V8U8.value: EnumAnnotation("16 Bits V8U8", "16-bit Bump Map format format (8 bits per color) "),
+        VX_PIXELFORMAT._32_V16U16.value: EnumAnnotation("32 Bits V16U16", "32-bit Bump Map format format (16 bits per color) "),
+        VX_PIXELFORMAT._16_L6V5U5.value: EnumAnnotation("16 Bits L6V5U5", "16-bit Bump Map format format with luminance "),
+        VX_PIXELFORMAT._32_X8L8V8U8.value: EnumAnnotation("32 Bits X8L8V8U8", "32-bit Bump Map format format with luminance "),
+        VX_PIXELFORMAT._8_ABGR8888_CLUT.value: EnumAnnotation("8 Bits ABGR8888 CLUT", "8 bits indexed CLUT (ABGR) "),
+        VX_PIXELFORMAT._8_ARGB8888_CLUT.value: EnumAnnotation("8 Bits ARGB8888 CLUT", "8 bits indexed CLUT (ARGB) "),
+        VX_PIXELFORMAT._4_ABGR8888_CLUT.value: EnumAnnotation("4 Bits ABGR8888 CLUT", "4 bits indexed CLUT (ABGR) "),
+        VX_PIXELFORMAT._4_ARGB8888_CLUT.value: EnumAnnotation("4 Bits ARGB8888 CLUT", "4 bits indexed CLUT (ARGB) "),
+    },
+    VXLIGHT_TYPE: {
+        VXLIGHT_TYPE.VX_LIGHTPOINT.value: EnumAnnotation("Point", "The Light is a point of light "),
+        VXLIGHT_TYPE.VX_LIGHTSPOT.value: EnumAnnotation("Spot", "The light is a spotlight "),
+        VXLIGHT_TYPE.VX_LIGHTDIREC.value: EnumAnnotation("Directional", "The light is directional light : Lights comes from an infinite point so only direction of light can be given "),
+        #VXLIGHT_TYPE.VX_LIGHTPARA.value: EnumAnnotation("Lightpara", "Obsolete, do not use "),
+    },
+    VXMESH_LITMODE: {
+        VXMESH_LITMODE.VX_PRELITMESH.value: EnumAnnotation("Prelit", "Lighting use color information store with vertices "),
+        VXMESH_LITMODE.VX_LITMESH.value: EnumAnnotation("Lit", "Lighting is done by renderer using normals and face material information. "),
+    }
+}
+
+class EnumPropHelper(UTIL_functions.EnumPropHelper):
+    """
+    Virtools type specified Blender EnumProp helper.
+    """
+    __mAnnotationDict: dict[int, EnumAnnotation]
+    __mEnumTy: type[enum.Enum]
+
+    def __init__(self, ty: type[enum.Enum]):
+        # set enum type and annotation ref first
+        self.__mEnumTy = ty
+        self.__mAnnotationDict = _g_Annotation[ty]
+        # init parent data
+        UTIL_functions.EnumPropHelper.__init__(
+            self,
+            self.__mEnumTy, # enum.Enum it self is iterable
+            lambda x: str(x.value), # convert enum.Enum's value to string
+            lambda x: self.__mEnumTy(int(x)),   # use stored enum type and int() to get enum member
+            lambda x: self.__mAnnotationDict[x.value].mDisplayName,
+            lambda x: self.__mAnnotationDict[x.value].mDescription,
+            lambda _: ''
+        )
+
+#endregion
+
+#region Virtools Blender Bridge Funcs & Vars
+
+def virtools_name_regulator(name: str | None) -> str:
+    if name: return name
+    else: return bpy.app.translations.pgettext_data('annoymous', 'BME/UTIL_virtools_types.virtools_name_regulator()')
+
+## Default Encoding for PyBMap
+#  Use semicolon split each encodings. Support Western European and Simplified Chinese in default.
+#  Since LibCmo 0.2, the encoding name of LibCmo become universal encoding which is platfoorm independent.
+#  So no need set it according to different platform.
+#  Use universal encoding name (like Python).
+g_PyBMapDefaultEncodings: tuple[str, ...] = (
+    'cp1252',
+    'gbk'
+)
+
+#endregion

bbp_ng/__init__.py

@@ -0,0 +1,327 @@
+#region Reload and Import
+
+# import core lib
+import bpy
+import typing, collections
+
+# reload if needed
+# TODO: finish reload feature if needed.
+# (reload script raise too much exceptions so I usually restart blender to test my plugin.)
+if "bpy" in locals():
+    import importlib
+
+#endregion
+
+# we must load icons manager first
+# and register it
+from . import UTIL_icons_manager
+UTIL_icons_manager.register()
+
+# then load other modules
+from . import UTIL_translation
+from . import PROP_preferences, PROP_ptrprop_resolver, PROP_virtools_material, PROP_virtools_texture, PROP_virtools_mesh, PROP_virtools_light, PROP_virtools_group
+from . import PROP_ballance_element, PROP_bme_material, PROP_ballance_map_info
+from . import OP_IMPORT_bmfile, OP_EXPORT_bmfile, OP_IMPORT_virtools, OP_EXPORT_virtools
+from . import OP_UV_flatten_uv, OP_UV_rail_uv
+from . import OP_MTL_fix_material
+from . import OP_ADDS_component, OP_ADDS_bme, OP_ADDS_rail
+from . import OP_OBJECT_legacy_align, OP_OBJECT_virtools_group, OP_OBJECT_snoop_group_then_to_mesh, OP_OBJECT_naming_convention
+
+#region Menu
+
+# ===== Menu Defines =====
+
+class BBP_MT_View3DMenu(bpy.types.Menu):
+    """Ballance 3D related operators"""
+    bl_idname = "BBP_MT_View3DMenu"
+    bl_label = "Ballance"
+    bl_translation_context = 'BBP_MT_View3DMenu'
+
+    def draw(self, context):
+        layout = self.layout
+        layout.label(text='UV', icon='UV', text_ctxt='BBP_MT_View3DMenu/draw')
+        layout.operator(OP_UV_flatten_uv.BBP_OT_flatten_uv.bl_idname)
+        layout.operator(OP_UV_rail_uv.BBP_OT_rail_uv.bl_idname)
+        layout.separator()
+        layout.label(text='Align', icon='SNAP_ON', text_ctxt='BBP_MT_View3DMenu/draw')
+        layout.operator(OP_OBJECT_legacy_align.BBP_OT_legacy_align.bl_idname)
+        layout.separator()
+        layout.label(text='Select', icon='SELECT_SET', text_ctxt='BBP_MT_View3DMenu/draw')
+        layout.operator(OP_OBJECT_virtools_group.BBP_OT_select_object_by_virtools_group.bl_idname)
+        layout.separator()
+        layout.label(text='Material', icon='MATERIAL', text_ctxt='BBP_MT_View3DMenu/draw')
+        layout.operator(OP_MTL_fix_material.BBP_OT_fix_all_material.bl_idname)
+
+class BBP_MT_AddBmeMenu(bpy.types.Menu):
+    """Add Ballance Floor"""
+    bl_idname = "BBP_MT_AddBmeMenu"
+    bl_label = "Floors"
+    bl_translation_context = 'BBP_MT_AddBmeMenu'
+
+    def draw(self, context):
+        layout = self.layout
+        OP_ADDS_bme.BBP_OT_add_bme_struct.draw_blc_menu(layout)
+        
+class BBP_MT_AddRailMenu(bpy.types.Menu):
+    """Add Ballance Rail"""
+    bl_idname = "BBP_MT_AddRailMenu"
+    bl_label = "Rails"
+    bl_translation_context = 'BBP_MT_AddRailMenu'
+
+    def draw(self, context):
+        layout = self.layout
+
+        layout.label(text="Sections", icon='MESH_CIRCLE', text_ctxt='BBP_MT_AddRailMenu/draw')
+        layout.operator(OP_ADDS_rail.BBP_OT_add_rail_section.bl_idname)
+        layout.operator(OP_ADDS_rail.BBP_OT_add_transition_section.bl_idname)
+
+        layout.separator()
+        layout.label(text="Straight Rails", icon='IPO_CONSTANT', text_ctxt='BBP_MT_AddRailMenu/draw')
+        layout.operator(OP_ADDS_rail.BBP_OT_add_straight_rail.bl_idname)
+        layout.operator(OP_ADDS_rail.BBP_OT_add_transition_rail.bl_idname)
+        layout.operator(OP_ADDS_rail.BBP_OT_add_side_rail.bl_idname)
+
+        layout.separator()
+        layout.label(text="Curve Rails", icon='MOD_SCREW', text_ctxt='BBP_MT_AddRailMenu/draw')
+        layout.operator(OP_ADDS_rail.BBP_OT_add_arc_rail.bl_idname)
+        layout.operator(OP_ADDS_rail.BBP_OT_add_spiral_rail.bl_idname)
+        layout.operator(OP_ADDS_rail.BBP_OT_add_side_spiral_rail.bl_idname)
+        
+class BBP_MT_AddComponentsMenu(bpy.types.Menu):
+    """Add Ballance Component"""
+    bl_idname = "BBP_MT_AddComponentsMenu"
+    bl_label = "Components"
+    bl_translation_context = 'BBP_MT_AddComponentsMenu'
+
+    def draw(self, context):
+        layout = self.layout
+
+        layout.label(text="Basic Components", text_ctxt='BBP_MT_AddComponentsMenu/draw')
+        OP_ADDS_component.BBP_OT_add_component.draw_blc_menu(layout)
+        
+        layout.separator()
+        layout.label(text="Nong Components", text_ctxt='BBP_MT_AddComponentsMenu/draw')
+        OP_ADDS_component.BBP_OT_add_nong_extra_point.draw_blc_menu(layout)
+        OP_ADDS_component.BBP_OT_add_nong_ventilator.draw_blc_menu(layout)
+
+        layout.separator()
+        layout.label(text="Series Components", text_ctxt='BBP_MT_AddComponentsMenu/draw')
+        OP_ADDS_component.BBP_OT_add_tilting_block_series.draw_blc_menu(layout)
+        OP_ADDS_component.BBP_OT_add_swing_series.draw_blc_menu(layout)
+        OP_ADDS_component.BBP_OT_add_ventilator_series.draw_blc_menu(layout)
+
+        layout.separator()
+        layout.label(text="Components Pair", text_ctxt='BBP_MT_AddComponentsMenu/draw')
+        OP_ADDS_component.BBP_OT_add_sector_component_pair.draw_blc_menu(layout)
+
+# ===== Menu Drawer =====
+
+MenuDrawer_t = typing.Callable[[typing.Any, typing.Any], None]
+
+def menu_drawer_import(self, context) -> None:
+    layout: bpy.types.UILayout = self.layout
+    # layout.operator(
+    #     OP_IMPORT_bmfile.BBP_OT_import_bmfile.bl_idname,
+    #     text="Ballance Map (.bmx)",
+    #     text_ctxt='BBP/__init__.menu_drawer_import()'
+    # )
+    layout.operator(
+        OP_IMPORT_virtools.BBP_OT_import_virtools.bl_idname,
+        text="Virtools File (.nmo/.cmo/.vmo) (experimental)",
+        text_ctxt='BBP/__init__.menu_drawer_import()'
+    )
+
+def menu_drawer_export(self, context) -> None:
+    layout: bpy.types.UILayout = self.layout
+    # layout.operator(
+    #     OP_EXPORT_bmfile.BBP_OT_export_bmfile.bl_idname,
+    #     text="Ballance Map (.bmx)",
+    #     text_ctxt='BBP/__init__.menu_drawer_export()'
+    # )
+    layout.operator(
+        OP_EXPORT_virtools.BBP_OT_export_virtools.bl_idname,
+        text="Virtools File (.nmo/.cmo/.vmo) (experimental)",
+        text_ctxt='BBP/__init__.menu_drawer_export()'
+    )
+
+def menu_drawer_view3d(self, context) -> None:
+    layout: bpy.types.UILayout = self.layout
+    layout.menu(BBP_MT_View3DMenu.bl_idname)
+
+def menu_drawer_add(self, context) -> None:
+    layout: bpy.types.UILayout = self.layout
+    layout.separator()
+    layout.label(text="Ballance", text_ctxt='BBP/__init__.menu_drawer_add()')
+    layout.menu(BBP_MT_AddBmeMenu.bl_idname, icon='MESH_CUBE')
+    layout.menu(BBP_MT_AddRailMenu.bl_idname, icon='MESH_CIRCLE')
+    layout.menu(BBP_MT_AddComponentsMenu.bl_idname, icon='MESH_ICOSPHERE')
+
+def menu_drawer_grouping(self, context) -> None:
+    layout: bpy.types.UILayout = self.layout
+    layout.separator()
+
+    # NOTE: because outline context may change operator context
+    # so it will cause no popup window when click operator in outline.
+    # thus we create a sub layout and set its operator context as 'INVOKE_DEFAULT'
+    # thus, all operators can pop up normally.
+    col = layout.column()
+    col.operator_context = 'INVOKE_DEFAULT'
+
+    col.label(text="Virtools Group", text_ctxt='BBP/__init__.menu_drawer_grouping()')
+    col.operator(
+        OP_OBJECT_virtools_group.BBP_OT_add_objects_virtools_group.bl_idname, icon='ADD', text="Group into...",
+        text_ctxt='BBP/__init__.menu_drawer_grouping()')
+    col.operator(
+        OP_OBJECT_virtools_group.BBP_OT_rm_objects_virtools_group.bl_idname, icon='REMOVE', text="Ungroup from...",
+        text_ctxt='BBP/__init__.menu_drawer_grouping()')
+    col.operator(
+        OP_OBJECT_virtools_group.BBP_OT_clear_objects_virtools_group.bl_idname, icon='TRASH', text="Clear All Groups",
+        text_ctxt='BBP/__init__.menu_drawer_grouping()')
+
+def menu_drawer_snoop_then_conv(self, context) -> None:
+    layout: bpy.types.UILayout = self.layout
+    layout.separator()
+    layout.label(text="Ballance", text_ctxt='BBP/__init__.menu_drawer_snoop_then_conv()')
+    layout.operator(OP_OBJECT_snoop_group_then_to_mesh.BBP_OT_snoop_group_then_to_mesh.bl_idname, icon='OUTLINER_OB_MESH')
+
+def menu_drawer_naming_convention(self, context) -> None:
+    layout: bpy.types.UILayout = self.layout
+    layout.separator()
+
+    # same reason in `menu_drawer_grouping()``
+    col = layout.column()
+    col.operator_context = 'INVOKE_DEFAULT'
+
+    col.label(text="Ballance", text_ctxt='BBP/__init__.menu_drawer_naming_convention()')
+    col.operator(OP_OBJECT_naming_convention.BBP_OT_regulate_objects_name.bl_idname, icon='GREASEPENCIL')
+    col.operator(OP_OBJECT_naming_convention.BBP_OT_auto_grouping.bl_idname, icon='GROUP')
+    col.operator(OP_OBJECT_naming_convention.BBP_OT_convert_to_imengyu.bl_idname, icon='ARROW_LEFTRIGHT')
+
+#endregion
+
+#region Register and Unregister.
+
+g_BldClasses: tuple[typing.Any, ...] = (
+    BBP_MT_View3DMenu,
+    BBP_MT_AddBmeMenu,
+    BBP_MT_AddRailMenu,
+    BBP_MT_AddComponentsMenu
+)
+
+class MenuEntry():
+    mContainerMenu: bpy.types.Menu
+    mIsAppend: bool
+    mMenuDrawer: MenuDrawer_t
+    def __init__(self, cont: bpy.types.Menu, is_append: bool, menu_func: MenuDrawer_t):
+        self.mContainerMenu = cont
+        self.mIsAppend = is_append
+        self.mMenuDrawer = menu_func
+
+g_BldMenus: tuple[MenuEntry, ...] = (
+     MenuEntry(bpy.types.VIEW3D_MT_editor_menus, False, menu_drawer_view3d),
+     MenuEntry(bpy.types.TOPBAR_MT_file_import, True, menu_drawer_import),
+     MenuEntry(bpy.types.TOPBAR_MT_file_export, True, menu_drawer_export),
+     MenuEntry(bpy.types.VIEW3D_MT_add, True, menu_drawer_add),
+
+     MenuEntry(bpy.types.VIEW3D_MT_object_context_menu, True, menu_drawer_snoop_then_conv),
+
+    # register double (for 2 menus)
+     MenuEntry(bpy.types.VIEW3D_MT_object_context_menu, True, menu_drawer_grouping),
+     MenuEntry(bpy.types.OUTLINER_MT_object, True, menu_drawer_grouping),
+
+     MenuEntry(bpy.types.OUTLINER_MT_collection, True, menu_drawer_naming_convention),
+)
+
+def register() -> None:
+    # register module
+    UTIL_translation.register()
+    PROP_preferences.register()
+
+    PROP_ptrprop_resolver.register()
+
+    PROP_virtools_material.register()
+    PROP_virtools_texture.register()
+    PROP_virtools_mesh.register()
+    PROP_virtools_light.register()
+    PROP_virtools_group.register()
+    PROP_ballance_element.register()
+    PROP_bme_material.register()
+    PROP_ballance_map_info.register()
+
+    OP_IMPORT_bmfile.register()
+    OP_EXPORT_bmfile.register()
+    OP_IMPORT_virtools.register()
+    OP_EXPORT_virtools.register()
+
+    OP_UV_rail_uv.register()
+    OP_UV_flatten_uv.register()
+
+    OP_MTL_fix_material.register()
+
+    OP_ADDS_component.register()
+    OP_ADDS_bme.register()
+    OP_ADDS_rail.register()
+
+    OP_OBJECT_legacy_align.register()
+    OP_OBJECT_virtools_group.register()
+    OP_OBJECT_snoop_group_then_to_mesh.register()
+    OP_OBJECT_naming_convention.register()
+
+    # register other classes
+    for cls in g_BldClasses:
+        bpy.utils.register_class(cls)
+
+    # add menu drawer
+    for entry in g_BldMenus:
+        if entry.mIsAppend:
+            entry.mContainerMenu.append(entry.mMenuDrawer)
+        else:
+            entry.mContainerMenu.prepend(entry.mMenuDrawer)
+
+def unregister() -> None:
+    # remove menu drawer
+    for entry in g_BldMenus:
+        entry.mContainerMenu.remove(entry.mMenuDrawer)
+
+    # unregister other classes
+    for cls in g_BldClasses:
+        bpy.utils.unregister_class(cls)
+
+    # unregister modules
+    OP_OBJECT_naming_convention.unregister()
+    OP_OBJECT_snoop_group_then_to_mesh.unregister()
+    OP_OBJECT_virtools_group.unregister()
+    OP_OBJECT_legacy_align.unregister()
+
+    OP_ADDS_rail.unregister()
+    OP_ADDS_bme.unregister()
+    OP_ADDS_component.unregister()
+
+    OP_MTL_fix_material.unregister()
+
+    OP_UV_flatten_uv.unregister()
+    OP_UV_rail_uv.unregister()
+
+    OP_EXPORT_virtools.unregister()
+    OP_IMPORT_virtools.unregister()
+    OP_EXPORT_bmfile.unregister()
+    OP_IMPORT_bmfile.unregister()
+
+    PROP_ballance_map_info.unregister()
+    PROP_bme_material.unregister()
+    PROP_ballance_element.unregister()
+    PROP_virtools_group.unregister()
+    PROP_virtools_light.unregister()
+    PROP_virtools_mesh.unregister()
+    PROP_virtools_texture.unregister()
+    PROP_virtools_material.unregister()
+    
+    PROP_ptrprop_resolver.unregister()
+
+    PROP_preferences.unregister()
+    UTIL_translation.unregister()
+
+if __name__ == "__main__":
+    register()
+
+#endregion

bbp_ng/blender_manifest.toml

@@ -0,0 +1,82 @@
+# Full context are copied from https://docs.blender.org/manual/en/dev/extensions/getting_started.html
+# Please note any update of this manifest
+
+schema_version = "1.0.0"
+
+# Example of manifest file for a Blender extension
+# Change the values according to your extension
+id = "bbp_ng"
+version = "4.2.0"
+name = "Ballance Blender Plugin"
+tagline = "The specialized add-on served for creating game map of Ballance"
+maintainer = "yyc12345 <yyc12321@outlook.com>"
+# Supported types: "add-on", "theme"
+type = "add-on"
+
+# 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/advanced/extensions/tags.html
+tags = ["Object", "Mesh", "UV", "Import-Export"]
+
+blender_version_min = "4.2.0"
+# # 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/advanced/extensions/licenses.html
+license = [
+  "SPDX:GPL-3.0-or-later",
+]
+# Optional: required by some licenses.
+# copyright = [
+#   "2002-2024 Developer Name",
+#   "1998 Company Name",
+# ]
+
+# 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/advanced/extensions/python_wheels.html
+# wheels = [
+#   "./wheels/hexdump-3.3-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.
+  "/i18n", # GNU gettext Translation.
+]

bbp_ng/raw_icons/README.md

@@ -0,0 +1,7 @@
+# Raw Icons
+
+This folder contain all images used by this Blender plugin.
+
+This folder should not be distributed in production because all of these files are in original size. It is pretty need too much time to load them in blender.  
+So we keep these high quality images here and provide a tools in `tools` folder. Builder should run script to generate thumbnails in `icons` folder.  
+Then this Blender plugin can work normally.