Bumped the minimum Blender version to 2.90.

Unrecognized sections are now simply ignored.

.github/FUNDING.yml

@@ -0,0 +1 @@
+ko_fi: cmbasnett

README.md

@@ -1,3 +1,49 @@
-# io_export_psk_psa
+This Blender 2.80+ add-on allows you to import and export meshes and animations to and from the [PSK and PSA file formats](https://wiki.beyondunreal.com/PSK_%26_PSA_file_formats) used in many versions of the Unreal Engine.
 
-If you are looking for a PSK/PSA importer, use [this one](https://github.com/Befzz/blender3d_import_psk_psa)!
+# Features
+* Full PSK/PSA import and export capabilities
+* Non-standard PSKX file format with vertex normals, extra UV channels and vertex colors is supported for import only
+* Fine-grained PSA sequence importing for efficient workflow when working with large PSA files
+* PSA sequence metadata (e.g., frame rate, sequence name) is preserved on import, allowing this data to be reused on export
+* Specific [bone groups](https://docs.blender.org/manual/en/latest/animation/armatures/properties/bone_groups.html) can be excluded from PSK/PSA export (useful for excluding non-contributing bones such as IK controllers)
+* PSA sequences can be exported directly from actions or delineated using a scene's [timeline markers](https://docs.blender.org/manual/en/latest/animation/markers.html), allowing direct use of the [NLA](https://docs.blender.org/manual/en/latest/editors/nla/index.html) when creating sequences 
+* Manual re-ordering of material slots when exporting multiple mesh objects.
+
+# Installation
+1. Download the zip file for the latest version from the [releases](https://github.com/DarklightGames/io_export_psk_psa/releases) page.
+2. Open Blender 2.80 or later.
+3. Navigate to the Blender Preferences (Edit > Preferences).
+4. Select the "Add-ons" tab.
+5. Click the "Install..." button.
+6. Select the .zip file that you downloaded earlier and click "Install Add-on".
+7. Enable the newly added "Import-Export: PSK/PSA Importer/Exporter" addon.
+
+# Usage
+## Exporting a PSK
+1. Select the mesh objects you wish to export.
+3. Navigate to File > Export > Unreal PSK (.psk)
+4. Enter the file name and click "Export".
+
+## Importing a PSK/PSKX
+1. Navigate to File > Import > Unreal PSK (.psk/.pskx)
+2. Select the PSK file you want to import and click "Import"
+
+## Exporting a PSA
+1. Select the armature objects you wish to export.
+2. Navigate to File > Export > Unreal PSA (.psa)
+3. Enter the file name and click "Export".
+
+## Importing a PSA
+1. Select the armature object that you wish you import actions to.
+2. Navigate to the Object Data Properties tab of the Properties editor.
+3. Navigate to the PSA Import panel.
+4. Click "Select PSA File".
+5. Select the PSA file that you want to import animations from and click "Select".
+6. In the Actions box, select which animations you want to import.
+7. Click "Import".
+
+# FAQ
+## Why are the mesh normals not accurate when importing a PSK extracted from [UE Viewer](https://www.gildor.org/en/projects/umodel)?
+If preserving the mesh normals of models is important for your workflow, it is *not recommended* to export PSK files from UE Viewer. This is because UE Viewer makes no attempt to reconstruct the original [smoothing groups](https://en.wikipedia.org/wiki/Smoothing_group). As a result, the normals of imported PSK files will be incorrect when imported into Blender and will need to be manually fixed.
+
+As a workaround, it is recommended to export [glTF](https://en.wikipedia.org/wiki/GlTF) meshes out of UE Viewer instead, since the glTF format has support for explicit normals and UE Viewer can correctly preserve the mesh normals on export. Note, however, that the imported glTF armature may have it's bones oriented incorrectly when imported into Blender. To mitigate this, you can combine the armature of PSK and the mesh of the glTF for best results.

io_export_psk_psa/__init__.py

@@ -1,73 +0,0 @@
-bl_info = {
-    "name": "PSK/PSA Exporter",
-    "author": "Colin Basnett",
-    "version": ( 1, 0, 0 ),
-    "blender": ( 2, 80, 0 ),
-    "location": "File > Export > PSK Export (.psk)",
-    "description": "PSK/PSA Export (.psk)",
-    "warning": "",
-    "wiki_url": "https://github.com/DarklightGames/io_export_psk_psa",
-    "tracker_url": "https://github.com/DarklightGames/io_export_psk_psa/issues",
-    "category": "Import-Export"
-}
-
-if 'bpy' in locals():
-    import importlib
-    importlib.reload(psk_data)
-    importlib.reload(psk_builder)
-    importlib.reload(psk_exporter)
-    importlib.reload(psk_operator)
-    importlib.reload(psa_data)
-    importlib.reload(psa_builder)
-    importlib.reload(psa_exporter)
-    importlib.reload(psa_operator)
-else:
-    # if i remove this line, it can be enabled just fine
-    from .psk import data as psk_data
-    from .psk import builder as psk_builder
-    from .psk import exporter as psk_exporter
-    from .psk import operator as psk_operator
-    from .psa import data as psa_data
-    from .psa import builder as psa_builder
-    from .psa import exporter as psa_exporter
-    from .psa import operator as psa_operator
-
-import bpy
-from bpy.props import IntProperty, CollectionProperty
-
-classes = [
-    psk_operator.PskExportOperator,
-    psa_operator.PsaExportOperator,
-    psa_operator.PSA_UL_ActionList,
-    psa_operator.ActionListItem
-]
-
-
-def psk_menu_func(self, context):
-    self.layout.operator(psk_operator.PskExportOperator.bl_idname, text ='Unreal PSK (.psk)')
-
-
-def psa_menu_func(self, context):
-    self.layout.operator(psa_operator.PsaExportOperator.bl_idname, text='Unreal PSA (.psa)')
-
-
-def register():
-    for cls in classes:
-        bpy.utils.register_class(cls)
-    bpy.types.TOPBAR_MT_file_export.append(psk_menu_func)
-    bpy.types.TOPBAR_MT_file_export.append(psa_menu_func)
-    bpy.types.Scene.psa_action_list = CollectionProperty(type=psa_operator.ActionListItem)
-    bpy.types.Scene.psa_action_list_index = IntProperty(name='index for list??', default=0)
-
-
-def unregister():
-    del bpy.types.Scene.psa_action_list_index
-    del bpy.types.Scene.psa_action_list
-    bpy.types.TOPBAR_MT_file_export.remove(psa_menu_func)
-    bpy.types.TOPBAR_MT_file_export.remove(psk_menu_func)
-    for cls in reversed(classes):
-        bpy.utils.unregister_class(cls)
-
-
-if __name__ == '__main__':
-    register()

io_export_psk_psa/data.py

@@ -1,31 +0,0 @@
-from ctypes import *
-
-
-class Vector3(Structure):
-    _fields_ = [
-        ('x', c_float),
-        ('y', c_float),
-        ('z', c_float),
-    ]
-
-
-class Quaternion(Structure):
-    _fields_ = [
-        ('x', c_float),
-        ('y', c_float),
-        ('z', c_float),
-        ('w', c_float),
-    ]
-
-
-class Section(Structure):
-    _fields_ = [
-        ('name', c_char * 20),
-        ('type_flags', c_int32),
-        ('data_size', c_int32),
-        ('data_count', c_int32)
-    ]
-
-    def __init__(self, *args, **kw):
-        super().__init__(*args, **kw)
-        self.type_flags = 1999801

io_export_psk_psa/psa/builder.py

@@ -1,130 +0,0 @@
-from .data import *
-
-
-class PsaBuilderOptions(object):
-    def __init__(self):
-        self.actions = []
-
-
-# https://git.cth451.me/cth451/blender-addons/blob/master/io_export_unreal_psk_psa.py
-class PsaBuilder(object):
-    def __init__(self):
-        # TODO: add options in here (selected anims, eg.)
-        pass
-
-    def build(self, context, options) -> Psa:
-        object = context.view_layer.objects.active
-
-        if object.type != 'ARMATURE':
-            raise RuntimeError('Selected object must be an Armature')
-
-        armature = object
-
-        if armature.animation_data is None:
-            raise RuntimeError('No animation data for armature')
-
-        psa = Psa()
-
-        bones = list(armature.data.bones)
-
-        # The order of the armature bones and the pose bones is not guaranteed to be the same.
-        # As as a result, we need to reconstruct the list of pose bones in the same order as the
-        # armature bones.
-        bone_names = [x.name for x in bones]
-        pose_bones = [(bone_names.index(bone.name), bone) for bone in armature.pose.bones]
-        pose_bones.sort(key=lambda x: x[0])
-        pose_bones = [x[1] for x in pose_bones]
-
-        for bone in bones:
-            psa_bone = Psa.Bone()
-            psa_bone.name = bytes(bone.name, encoding='utf-8')
-            psa_bone.children_count = len(bone.children)
-
-            try:
-                psa_bone.parent_index = bones.index(bone.parent)
-            except ValueError:
-                psa_bone.parent_index = -1
-
-            if bone.parent is not None:
-                rotation = bone.matrix.to_quaternion()
-                rotation.x = -rotation.x
-                rotation.y = -rotation.y
-                rotation.z = -rotation.z
-                quat_parent = bone.parent.matrix.to_quaternion().inverted()
-                parent_head = quat_parent @ bone.parent.head
-                parent_tail = quat_parent @ bone.parent.tail
-                location = (parent_tail - parent_head) + bone.head
-            else:
-                location = armature.matrix_local @ bone.head
-                rot_matrix = bone.matrix @ armature.matrix_local.to_3x3()
-                rotation = rot_matrix.to_quaternion()
-
-            psa_bone.location.x = location.x
-            psa_bone.location.y = location.y
-            psa_bone.location.z = location.z
-
-            psa_bone.rotation.x = rotation.x
-            psa_bone.rotation.y = rotation.y
-            psa_bone.rotation.z = rotation.z
-            psa_bone.rotation.w = rotation.w
-
-            psa.bones.append(psa_bone)
-
-        frame_start_index = 0
-
-        for action in options.actions:
-            if len(action.fcurves) == 0:
-                continue
-
-            armature.animation_data.action = action
-            context.view_layer.update()
-
-            frame_min, frame_max = [int(x) for x in action.frame_range]
-
-            sequence = Psa.Sequence()
-            sequence.name = bytes(action.name, encoding='utf-8')
-            sequence.frame_count = frame_max - frame_min + 1
-            sequence.frame_start_index = frame_start_index
-            sequence.fps = 30  # TODO: fill in later with r
-
-            frame_count = frame_max - frame_min + 1
-
-            for frame in range(frame_count):
-                context.scene.frame_set(frame)
-
-                for bone in pose_bones:
-                    # TODO: is the cast-to-matrix necessary? (guessing no)
-                    key = Psa.Key()
-                    pose_bone_matrix = bone.matrix
-
-                    if bone.parent is not None:
-                        pose_bone_parent_matrix = bone.parent.matrix
-                        pose_bone_matrix = pose_bone_parent_matrix.inverted() @ pose_bone_matrix
-
-                    location = pose_bone_matrix.to_translation()
-                    rotation = pose_bone_matrix.to_quaternion().normalized()
-
-                    if bone.parent is not None:
-                        rotation.x = -rotation.x
-                        rotation.y = -rotation.y
-                        rotation.z = -rotation.z
-
-                    key.location.x = location.x
-                    key.location.y = location.y
-                    key.location.z = location.z
-                    key.rotation.x = rotation.x
-                    key.rotation.y = rotation.y
-                    key.rotation.z = rotation.z
-                    key.rotation.w = rotation.w
-                    key.time = 1.0 / sequence.fps
-
-                    psa.keys.append(key)
-
-                frame_start_index += 1
-
-                sequence.bone_count = len(pose_bones)
-                sequence.track_time = frame_count
-
-            psa.sequences.append(sequence)
-
-        return psa

io_export_psk_psa/psa/exporter.py

@@ -1,27 +0,0 @@
-from typing import Type
-from .data import *
-
-
-class PsaExporter(object):
-    def __init__(self, psa: Psa):
-        self.psa: Psa = psa
-
-    # This method is shared by both PSA/K file formats, move this?
-    @staticmethod
-    def write_section(fp, name: bytes, data_type: Type[Structure] = None, data: list = None):
-        section = Section()
-        section.name = name
-        if data_type is not None and data is not None:
-            section.data_size = sizeof(data_type)
-            section.data_count = len(data)
-        fp.write(section)
-        if data is not None:
-            for datum in data:
-                fp.write(datum)
-
-    def export(self, path: str):
-        with open(path, 'wb') as fp:
-            self.write_section(fp, b'ANIMHEAD')
-            self.write_section(fp, b'BONENAMES', Psa.Bone, self.psa.bones)
-            self.write_section(fp, b'ANIMINFO', Psa.Sequence, self.psa.sequences)
-            self.write_section(fp, b'ANIMKEYS', Psa.Key, self.psa.keys)

io_export_psk_psa/psa/operator.py

@@ -1,104 +0,0 @@
-from bpy.types import Operator, Action, UIList, PropertyGroup
-from bpy_extras.io_utils import ExportHelper
-from bpy.props import StringProperty, BoolProperty, CollectionProperty, PointerProperty
-from .builder import PsaBuilder, PsaBuilderOptions
-from .exporter import PsaExporter
-import bpy
-import re
-
-
-class ActionListItem(PropertyGroup):
-    action: PointerProperty(type=Action)
-    is_selected: BoolProperty(default=False)
-
-    @property
-    def name(self):
-        return self.action.name
-
-
-class PSA_UL_ActionList(UIList):
-    def draw_item(self, context, layout, data, item, icon, active_data, active_propname, index):
-        layout.alignment = 'LEFT'
-        layout.prop(item, 'is_selected', icon_only=True)
-        layout.label(text=item.action.name)
-
-    def filter_items(self, context, data, property):
-        # TODO: returns two lists, apparently
-        actions = getattr(data, property)
-        flt_flags = []
-        flt_neworder = []
-        if self.filter_name:
-            flt_flags = bpy.types.UI_UL_list.filter_items_by_name(self.filter_name, self.bitflag_filter_item, actions, 'name', reverse=self.use_filter_invert)
-        return flt_flags, flt_neworder
-
-
-class PsaExportOperator(Operator, ExportHelper):
-    bl_idname = 'export.psa'
-    bl_label = 'Export'
-    __doc__ = 'PSA Exporter (.psa)'
-    filename_ext = '.psa'
-    filter_glob : StringProperty(default='*.psa', options={'HIDDEN'})
-    filepath : StringProperty(
-        name='File Path',
-        description='File path used for exporting the PSA file',
-        maxlen=1024,
-        default='')
-
-    def __init__(self):
-        self.armature = None
-
-    def draw(self, context):
-        layout = self.layout
-        scene = context.scene
-        box = layout.box()
-        box.label(text='Actions', icon='ACTION')
-        row = box.row()
-        row.template_list('PSA_UL_ActionList', 'asd', scene, 'psa_action_list', scene, 'psa_action_list_index', rows=len(context.scene.psa_action_list))
-
-    def is_action_for_armature(self, action):
-        bone_names = [x.name for x in self.armature.data.bones]
-        print(bone_names)
-        for fcurve in action.fcurves:
-            match = re.match('pose\.bones\["(.+)"\].\w+', fcurve.data_path)
-            if not match:
-                continue
-            bone_name = match.group(1)
-            if bone_name not in bone_names:
-                return False
-        return True
-
-    def invoke(self, context, event):
-        if context.view_layer.objects.active.type != 'ARMATURE':
-            self.report({'ERROR_INVALID_CONTEXT'}, 'The selected object must be an armature.')
-            return {'CANCELLED'}
-
-        self.armature = context.view_layer.objects.active
-
-        context.scene.psa_action_list.clear()
-        for action in bpy.data.actions:
-            item = context.scene.psa_action_list.add()
-            item.action = action
-            if self.is_action_for_armature(action):
-                item.is_selected = True
-
-        if len(context.scene.psa_action_list) == 0:
-            self.report({'ERROR_INVALID_CONTEXT'}, 'There are no actions to export.')
-            return {'CANCELLED'}
-
-        context.window_manager.fileselect_add(self)
-        return {'RUNNING_MODAL'}
-
-    def execute(self, context):
-        actions = [x.action for x in context.scene.psa_action_list if x.is_selected]
-
-        if len(actions) == 0:
-            self.report({'ERROR_INVALID_CONTEXT'}, 'No actions were selected for export.')
-            return {'CANCELLED'}
-
-        options = PsaBuilderOptions()
-        options.actions = actions
-        builder = PsaBuilder()
-        psk = builder.build(context, options)
-        exporter = PsaExporter(psk)
-        exporter.export(self.filepath)
-        return {'FINISHED'}

io_export_psk_psa/psk/builder.py

@@ -1,158 +0,0 @@
-import bpy
-import bmesh
-from .data import *
-
-
-class PskBuilder(object):
-    def __init__(self):
-        # TODO: add options in here
-        pass
-
-    def build(self, context) -> Psk:
-        object = context.view_layer.objects.active
-
-        if object.type != 'MESH':
-            raise RuntimeError('Selected object must be a mesh')
-
-        if len(object.data.materials) == 0:
-            raise RuntimeError('Mesh must have at least one material')
-
-        # ensure that there is exactly one armature modifier
-        modifiers = [x for x in object.modifiers if x.type == 'ARMATURE']
-
-        if len(modifiers) != 1:
-            raise RuntimeError('Mesh must have one armature modifier')
-
-        armature_modifier = modifiers[0]
-        armature_object = armature_modifier.object
-
-        if armature_object is None:
-            raise RuntimeError('Armature modifier has no linked object')
-
-        # TODO: probably requires at least one bone? not sure
-        mesh_data = object.data
-
-        # TODO: if there is an edge-split modifier, we need to apply it (maybe?)
-
-        # TODO: duplicate all the data
-        mesh = bpy.data.meshes.new('export')
-
-        # copy the contents of the mesh
-        bm = bmesh.new()
-        bm.from_mesh(mesh_data)
-        bmesh.ops.triangulate(bm, faces=bm.faces)
-        bm.to_mesh(mesh)
-        bm.free()
-        del bm
-
-        psk = Psk()
-
-        # VERTICES
-        for vertex in object.data.vertices:
-            point = Vector3()
-            point.x = vertex.co.x
-            point.y = vertex.co.y
-            point.z = vertex.co.z
-            psk.points.append(point)
-
-        # WEDGES
-        uv_layer = object.data.uv_layers.active.data
-        if len(object.data.loops) <= 65536:
-            wedge_type = Psk.Wedge16
-        else:
-            wedge_type = Psk.Wedge32
-        psk.wedges = [wedge_type() for _ in range(len(object.data.loops))]
-
-        for loop_index, loop in enumerate(object.data.loops):
-            wedge = psk.wedges[loop_index]
-            wedge.material_index = 0
-            wedge.point_index = loop.vertex_index
-            wedge.u, wedge.v = uv_layer[loop_index].uv
-            wedge.v = 1.0 - wedge.v
-            psk.wedges.append(wedge)
-
-        # MATERIALS
-        for i, m in enumerate(object.data.materials):
-            if m is None:
-                raise RuntimeError('Material cannot be empty (index ' + str(i) + ')')
-            material = Psk.Material()
-            material.name = bytes(m.name, encoding='utf-8')
-            material.texture_index = i
-            psk.materials.append(material)
-
-        # FACES
-        # TODO: this is making the assumption that the mesh is triangulated
-        object.data.calc_loop_triangles()
-        poly_groups, groups = object.data.calc_smooth_groups(use_bitflags=True)
-        for f in object.data.loop_triangles:
-            face = Psk.Face()
-            face.material_index = f.material_index
-            face.wedge_index_1 = f.loops[2]
-            face.wedge_index_2 = f.loops[1]
-            face.wedge_index_3 = f.loops[0]
-            face.smoothing_groups = poly_groups[f.polygon_index]
-            psk.faces.append(face)
-            # update the material index of the wedges
-            for i in range(3):
-                psk.wedges[f.loops[i]].material_index = f.material_index
-
-        # https://github.com/bwrsandman/blender-addons/blob/master/io_export_unreal_psk_psa.py
-        bones = list(armature_object.data.bones)
-        for bone in bones:
-            psk_bone = Psk.Bone()
-            psk_bone.name = bytes(bone.name, encoding='utf-8')
-            psk_bone.flags = 0
-            psk_bone.children_count = len(bone.children)
-
-            try:
-                psk_bone.parent_index = bones.index(bone.parent)
-            except ValueError:
-                psk_bone.parent_index = 0
-
-            if bone.parent is not None:
-                rotation = bone.matrix.to_quaternion()
-                rotation.x = -rotation.x
-                rotation.y = -rotation.y
-                rotation.z = -rotation.z
-                quat_parent = bone.parent.matrix.to_quaternion().inverted()
-                parent_head = quat_parent @ bone.parent.head
-                parent_tail = quat_parent @ bone.parent.tail
-                location = (parent_tail - parent_head) + bone.head
-            else:
-                location = armature_object.matrix_local @ bone.head
-                rot_matrix = bone.matrix @ armature_object.matrix_local.to_3x3()
-                rotation = rot_matrix.to_quaternion()
-
-            psk_bone.location.x = location.x
-            psk_bone.location.y = location.y
-            psk_bone.location.z = location.z
-
-            psk_bone.rotation.x = rotation.x
-            psk_bone.rotation.y = rotation.y
-            psk_bone.rotation.z = rotation.z
-            psk_bone.rotation.w = rotation.w
-
-            psk.bones.append(psk_bone)
-
-        # WEIGHTS
-        # TODO: bone ~> vg might not be 1:1, provide a nice error message if this is the case
-        armature = armature_object.data
-        bone_names = [x.name for x in armature.bones]
-        vertex_group_names = [x.name for x in object.vertex_groups]
-        bone_indices = [bone_names.index(name) for name in vertex_group_names]
-        for vertex_group_index, vertex_group in enumerate(object.vertex_groups):
-            bone_index = bone_indices[vertex_group_index]
-            for vertex_index in range(len(object.data.vertices)):
-                try:
-                    weight = vertex_group.weight(vertex_index)
-                except RuntimeError:
-                    continue
-                if weight == 0.0:
-                    continue
-                w = Psk.Weight()
-                w.bone_index = bone_index
-                w.point_index = vertex_index
-                w.weight = weight
-                psk.weights.append(w)
-
-        return psk

io_export_psk_psa/psk/exporter.py

@@ -1,38 +0,0 @@
-from typing import Type
-from .data import *
-
-
-class PskExporter(object):
-    def __init__(self, psk: Psk):
-        self.psk: Psk = psk
-
-    @staticmethod
-    def write_section(fp, name: bytes, data_type: Type[Structure] = None, data: list = None):
-        section = Section()
-        section.name = name
-        if data_type is not None and data is not None:
-            section.data_size = sizeof(data_type)
-            section.data_count = len(data)
-        fp.write(section)
-        if data is not None:
-            for datum in data:
-                fp.write(datum)
-
-    def export(self, path: str):
-        # TODO: add logic somewhere to assert lengths of ctype structs
-        with open(path, 'wb') as fp:
-            self.write_section(fp, b'ACTRHEAD')
-            self.write_section(fp, b'PNTS0000', Vector3, self.psk.points)
-
-            # WEDGES
-            # TODO: this really should be on the level of the builder, not the exporter
-            if len(self.psk.wedges) <= 65536:
-                wedge_type = Psk.Wedge16
-            else:
-                wedge_type = Psk.Wedge32
-
-            self.write_section(fp, b'VTXW0000', wedge_type, self.psk.wedges)
-            self.write_section(fp, b'FACE0000', Psk.Face, self.psk.faces)
-            self.write_section(fp, b'MATT0000', Psk.Material, self.psk.materials)
-            self.write_section(fp, b'REFSKELT', Psk.Bone, self.psk.bones)
-            self.write_section(fp, b'RAWWEIGHTS', Psk.Weight, self.psk.weights)

io_export_psk_psa/psk/operator.py

@@ -1,26 +0,0 @@
-from bpy.types import Operator
-from bpy_extras.io_utils import ExportHelper
-from bpy.props import StringProperty, BoolProperty, FloatProperty
-from .builder import PskBuilder
-from .exporter import PskExporter
-
-
-class PskExportOperator(Operator, ExportHelper):
-    bl_idname = 'export.psk'
-    bl_label = 'Export'
-    __doc__ = 'PSK Exporter (.psk)'
-    filename_ext = '.psk'
-    filter_glob: StringProperty(default='*.psk', options={'HIDDEN'})
-
-    filepath: StringProperty(
-        name='File Path',
-        description='File path used for exporting the PSK file',
-        maxlen=1024,
-        default='')
-
-    def execute(self, context):
-        builder = PskBuilder()
-        psk = builder.build(context)
-        exporter = PskExporter(psk)
-        exporter.export(self.filepath)
-        return {'FINISHED'}

io_scene_psk_psa/__init__.py

@@ -0,0 +1,93 @@
+bl_info = {
+    "name": "PSK/PSA Importer/Exporter",
+    "author": "Colin Basnett, Yurii Ti",
+    "version": (4, 2, 1),
+    "blender": (2, 90, 0),
+    # "location": "File > Export > PSK Export (.psk)",
+    "description": "PSK/PSA Import/Export (.psk/.psa)",
+    "warning": "",
+    "doc_url": "https://github.com/DarklightGames/io_scene_psk_psa",
+    "tracker_url": "https://github.com/DarklightGames/io_scene_psk_psa/issues",
+    "category": "Import-Export"
+}
+
+if 'bpy' in locals():
+    import importlib
+
+    importlib.reload(psx_data)
+    importlib.reload(psx_helpers)
+    importlib.reload(psx_types)
+    importlib.reload(psk_data)
+    importlib.reload(psk_builder)
+    importlib.reload(psk_exporter)
+    importlib.reload(psk_importer)
+    importlib.reload(psk_reader)
+    importlib.reload(psa_data)
+    importlib.reload(psa_builder)
+    importlib.reload(psa_exporter)
+    importlib.reload(psa_reader)
+    importlib.reload(psa_importer)
+else:
+    # if i remove this line, it can be enabled just fine
+    from . import data as psx_data
+    from . import helpers as psx_helpers
+    from . import types as psx_types
+    from .psk import data as psk_data
+    from .psk import builder as psk_builder
+    from .psk import exporter as psk_exporter
+    from .psk import reader as psk_reader
+    from .psk import importer as psk_importer
+    from .psa import data as psa_data
+    from .psa import builder as psa_builder
+    from .psa import exporter as psa_exporter
+    from .psa import reader as psa_reader
+    from .psa import importer as psa_importer
+
+import bpy
+from bpy.props import PointerProperty
+
+classes = (psx_types.classes +
+           psk_importer.classes +
+           psk_exporter.classes +
+           psa_exporter.classes +
+           psa_importer.classes)
+
+
+def psk_export_menu_func(self, context):
+    self.layout.operator(psk_exporter.PskExportOperator.bl_idname, text='Unreal PSK (.psk)')
+
+
+def psk_import_menu_func(self, context):
+    self.layout.operator(psk_importer.PskImportOperator.bl_idname, text='Unreal PSK (.psk/.pskx)')
+
+
+def psa_export_menu_func(self, context):
+    self.layout.operator(psa_exporter.PsaExportOperator.bl_idname, text='Unreal PSA (.psa)')
+
+
+def register():
+    for cls in classes:
+        bpy.utils.register_class(cls)
+    bpy.types.TOPBAR_MT_file_export.append(psk_export_menu_func)
+    bpy.types.TOPBAR_MT_file_import.append(psk_import_menu_func)
+    bpy.types.TOPBAR_MT_file_export.append(psa_export_menu_func)
+    bpy.types.Scene.psa_import = PointerProperty(type=psa_importer.PsaImportPropertyGroup)
+    bpy.types.Scene.psk_import = PointerProperty(type=psk_importer.PskImportPropertyGroup)
+    bpy.types.Scene.psa_export = PointerProperty(type=psa_exporter.PsaExportPropertyGroup)
+    bpy.types.Scene.psk_export = PointerProperty(type=psk_exporter.PskExportPropertyGroup)
+
+
+def unregister():
+    del bpy.types.Scene.psa_import
+    del bpy.types.Scene.psk_import
+    del bpy.types.Scene.psa_export
+    del bpy.types.Scene.psk_export
+    bpy.types.TOPBAR_MT_file_export.remove(psk_export_menu_func)
+    bpy.types.TOPBAR_MT_file_import.remove(psk_import_menu_func)
+    bpy.types.TOPBAR_MT_file_export.remove(psa_export_menu_func)
+    for cls in reversed(classes):
+        bpy.utils.unregister_class(cls)
+
+
+if __name__ == '__main__':
+    register()

io_scene_psk_psa/data.py

@@ -0,0 +1,95 @@
+from ctypes import *
+from typing import Tuple
+
+
+class Color(Structure):
+    _fields_ = [
+        ('r', c_ubyte),
+        ('g', c_ubyte),
+        ('b', c_ubyte),
+        ('a', c_ubyte),
+    ]
+
+    def __iter__(self):
+        yield self.r
+        yield self.g
+        yield self.b
+        yield self.a
+
+    def __eq__(self, other):
+        return all(map(lambda x: x[0] == x[1], zip(self, other)))
+
+    def __repr__(self):
+        return repr(tuple(self))
+
+    def normalized(self) -> Tuple:
+        return tuple(map(lambda x: x / 255.0, iter(self)))
+
+
+class Vector2(Structure):
+    _fields_ = [
+        ('x', c_float),
+        ('y', c_float),
+    ]
+
+    def __iter__(self):
+        yield self.x
+        yield self.y
+
+    def __repr__(self):
+        return repr(tuple(self))
+
+
+class Vector3(Structure):
+    _fields_ = [
+        ('x', c_float),
+        ('y', c_float),
+        ('z', c_float),
+    ]
+
+    def __iter__(self):
+        yield self.x
+        yield self.y
+        yield self.z
+
+    def __repr__(self):
+        return repr(tuple(self))
+
+    @classmethod
+    def zero(cls):
+        return Vector3(0, 0, 0)
+
+
+class Quaternion(Structure):
+    _fields_ = [
+        ('x', c_float),
+        ('y', c_float),
+        ('z', c_float),
+        ('w', c_float),
+    ]
+
+    def __iter__(self):
+        yield self.w
+        yield self.x
+        yield self.y
+        yield self.z
+
+    def __repr__(self):
+        return repr(tuple(self))
+
+    @classmethod
+    def identity(cls):
+        return Quaternion(0, 0, 0, 1)
+
+
+class Section(Structure):
+    _fields_ = [
+        ('name', c_char * 20),
+        ('type_flags', c_int32),
+        ('data_size', c_int32),
+        ('data_count', c_int32)
+    ]
+
+    def __init__(self, *args, **kw):
+        super().__init__(*args, **kw)
+        self.type_flags = 1999801

io_scene_psk_psa/helpers.py

@@ -0,0 +1,176 @@
+import datetime
+import re
+from collections import Counter
+from typing import List, Iterable
+
+import bpy.types
+from bpy.types import NlaStrip, Object
+
+
+class Timer:
+    def __enter__(self):
+        self.start = datetime.datetime.now()
+        self.interval = None
+        return self
+
+    def __exit__(self, *args):
+        self.end = datetime.datetime.now()
+        self.interval = self.end - self.start
+
+    @property
+    def duration(self):
+        if self.interval is not None:
+            return self.interval
+        else:
+            return datetime.datetime.now() - self.start
+
+
+def rgb_to_srgb(c):
+    if c > 0.0031308:
+        return 1.055 * (pow(c, (1.0 / 2.4))) - 0.055
+    else:
+        return 12.92 * c
+
+
+def get_nla_strips_in_timeframe(animation_data, frame_min, frame_max) -> List[NlaStrip]:
+    if animation_data is None:
+        return []
+    strips = []
+    for nla_track in animation_data.nla_tracks:
+        if nla_track.mute:
+            continue
+        for strip in nla_track.strips:
+            if (strip.frame_start < frame_min and strip.frame_end > frame_max) or \
+                    (frame_min <= strip.frame_start < frame_max) or \
+                    (frame_min < strip.frame_end <= frame_max):
+                strips.append(strip)
+    return strips
+
+
+def populate_bone_group_list(armature_object: Object, bone_group_list: bpy.props.CollectionProperty) -> None:
+    """
+    Updates the bone group collection.
+
+    Bone group selections are preserved between updates unless none of the groups were previously selected;
+    otherwise, all groups are selected by default.
+    """
+    has_selected_groups = any([g.is_selected for g in bone_group_list])
+    unassigned_group_is_selected, selected_assigned_group_names = True, []
+
+    if has_selected_groups:
+        # Preserve group selections before clearing the list.
+        # We handle selections for the unassigned group separately to cover the edge case
+        # where there might be an actual group with 'Unassigned' as its name.
+        unassigned_group_idx, unassigned_group_is_selected = next(iter([
+            (i, g.is_selected) for i, g in enumerate(bone_group_list) if g.index == -1]), (-1, False))
+
+        selected_assigned_group_names = [
+            g.name for i, g in enumerate(bone_group_list) if i != unassigned_group_idx and g.is_selected]
+
+    bone_group_list.clear()
+
+    if armature_object and armature_object.pose:
+        bone_group_counts = Counter(map(lambda x: x.bone_group, armature_object.pose.bones))
+
+        item = bone_group_list.add()
+        item.name = 'Unassigned'
+        item.index = -1
+        item.count = 0 if None not in bone_group_counts else bone_group_counts[None]
+        item.is_selected = unassigned_group_is_selected
+
+        for bone_group_index, bone_group in enumerate(armature_object.pose.bone_groups):
+            item = bone_group_list.add()
+            item.name = bone_group.name
+            item.index = bone_group_index
+            item.count = 0 if bone_group not in bone_group_counts else bone_group_counts[bone_group]
+            item.is_selected = bone_group.name in selected_assigned_group_names if has_selected_groups else True
+
+
+def get_psa_sequence_name(action, should_use_original_sequence_name):
+    if should_use_original_sequence_name and 'psa_sequence_name' in action:
+        return action['psa_sequence_name']
+    else:
+        return action.name
+
+
+def check_bone_names(bone_names: Iterable[str]):
+    pattern = re.compile(r'^[a-zA-Z\d_\- ]+$')
+    invalid_bone_names = [x for x in bone_names if pattern.match(x) is None]
+    if len(invalid_bone_names) > 0:
+        raise RuntimeError(f'The following bone names are invalid: {invalid_bone_names}.\n'
+                           f'Bone names must only contain letters, numbers, spaces, hyphens and underscores.')
+
+
+def get_export_bone_names(armature_object, bone_filter_mode, bone_group_indices: List[int]) -> List[str]:
+    """
+    Returns a sorted list of bone indices that should be exported for the given bone filter mode and bone groups.
+
+    Note that the ancestors of bones within the bone groups will also be present in the returned list.
+
+    :param armature_object: Blender object with type 'ARMATURE'
+    :param bone_filter_mode: One of ['ALL', 'BONE_GROUPS']
+    :param bone_group_indices: List of bone group indices to be exported.
+    :return: A sorted list of bone indices that should be exported.
+    """
+    if armature_object is None or armature_object.type != 'ARMATURE':
+        raise ValueError('An armature object must be supplied')
+
+    bones = armature_object.data.bones
+    pose_bones = armature_object.pose.bones
+    bone_names = [x.name for x in bones]
+
+    # Get a list of the bone indices that we are explicitly including.
+    bone_index_stack = []
+    is_exporting_none_bone_groups = -1 in bone_group_indices
+    for bone_index, pose_bone in enumerate(pose_bones):
+        if bone_filter_mode == 'ALL' or \
+                (pose_bone.bone_group is None and is_exporting_none_bone_groups) or \
+                (pose_bone.bone_group is not None and pose_bone.bone_group_index in bone_group_indices):
+            bone_index_stack.append((bone_index, None))
+
+    # For each bone that is explicitly being added, recursively walk up the hierarchy and ensure that all of
+    # those ancestor bone indices are also in the list.
+    bone_indices = dict()
+    while len(bone_index_stack) > 0:
+        bone_index, instigator_bone_index = bone_index_stack.pop()
+        bone = bones[bone_index]
+        if bone.parent is not None:
+            parent_bone_index = bone_names.index(bone.parent.name)
+            if parent_bone_index not in bone_indices:
+                bone_index_stack.append((parent_bone_index, bone_index))
+        bone_indices[bone_index] = instigator_bone_index
+
+    # Sort the bone index list in-place.
+    bone_indices = [(x[0], x[1]) for x in bone_indices.items()]
+    bone_indices.sort(key=lambda x: x[0])
+
+    # Split out the bone indices and the instigator bone names into separate lists.
+    # We use the bone names for the return values because the bone name is a more universal way of referencing them.
+    # For example, users of this function may modify bone lists, which would invalidate the indices and require a
+    # index mapping scheme to resolve it. Using strings is more comfy and results in less code downstream.
+    instigator_bone_names = [bones[x[1]].name if x[1] is not None else None for x in bone_indices]
+    bone_names = [bones[x[0]].name for x in bone_indices]
+
+    # Ensure that the hierarchy we are sending back has a single root bone.
+    bone_indices = [x[0] for x in bone_indices]
+    root_bones = [bones[bone_index] for bone_index in bone_indices if bones[bone_index].parent is None]
+    if len(root_bones) > 1:
+        # There is more than one root bone.
+        # Print out why each root bone was included by linking it to one of the explicitly included bones.
+        root_bone_names = [bone.name for bone in root_bones]
+        for root_bone_name in root_bone_names:
+            bone_name = root_bone_name
+            while True:
+                # Traverse the instigator chain until the end to find the true instigator bone.
+                # TODO: in future, it would be preferential to have a readout of *all* instigator bones.
+                instigator_bone_name = instigator_bone_names[bone_names.index(bone_name)]
+                if instigator_bone_name is None:
+                    print(f'Root bone "{root_bone_name}" was included because {bone_name} was marked for export')
+                    break
+                bone_name = instigator_bone_name
+
+        raise RuntimeError('Exported bone hierarchy must have a single root bone.\n'
+                           f'The bone hierarchy marked for export has {len(root_bones)} root bones: {root_bone_names}.\n'
+                           f'Additional debugging information has been written to the console.')
+
+    return bone_names

io_scene_psk_psa/psa/builder.py

@@ -0,0 +1,298 @@
+from typing import Dict
+
+from bpy.types import Action, Armature, Bone
+
+from .data import *
+from ..helpers import *
+
+
+class PsaBuildOptions(object):
+    def __init__(self):
+        self.should_override_animation_data = False
+        self.animation_data_override = None
+        self.fps_source = 'SCENE'
+        self.fps_custom = 30.0
+        self.sequence_source = 'ACTIONS'
+        self.actions = []
+        self.marker_names = []
+        self.bone_filter_mode = 'ALL'
+        self.bone_group_indices = []
+        self.should_use_original_sequence_names = False
+        self.should_trim_timeline_marker_sequences = True
+        self.should_ignore_bone_name_restrictions = False
+        self.sequence_name_prefix = ''
+        self.sequence_name_suffix = ''
+        self.root_motion = False
+
+
+def get_sequence_fps(context, options: PsaBuildOptions, actions: Iterable[Action]) -> float:
+    if options.fps_source == 'SCENE':
+        return context.scene.render.fps
+    if options.fps_source == 'CUSTOM':
+        return options.fps_custom
+    elif options.fps_source == 'ACTION_METADATA':
+        # Get the minimum value of action metadata FPS values.
+        fps_list = []
+        for action in filter(lambda x: 'psa_sequence_fps' in x, actions):
+            fps = action['psa_sequence_fps']
+            if type(fps) == int or type(fps) == float:
+                fps_list.append(fps)
+        if len(fps_list) > 0:
+            return min(fps_list)
+        else:
+            # No valid action metadata to use, fallback to scene FPS
+            return context.scene.render.fps
+    else:
+        raise RuntimeError(f'Invalid FPS source "{options.fps_source}"')
+
+
+def get_timeline_marker_sequence_frame_ranges(animation_data, context, options: PsaBuildOptions) -> Dict:
+    # Timeline markers need to be sorted so that we can determine the sequence start and end positions.
+    sequence_frame_ranges = dict()
+    sorted_timeline_markers = list(sorted(context.scene.timeline_markers, key=lambda x: x.frame))
+    sorted_timeline_marker_names = list(map(lambda x: x.name, sorted_timeline_markers))
+
+    for marker_name in options.marker_names:
+        marker = context.scene.timeline_markers[marker_name]
+        frame_min = marker.frame
+        # Determine the final frame of the sequence based on the next marker.
+        # If no subsequent marker exists, use the maximum frame_end from all NLA strips.
+        marker_index = sorted_timeline_marker_names.index(marker_name)
+        next_marker_index = marker_index + 1
+        frame_max = 0
+        if next_marker_index < len(sorted_timeline_markers):
+            # There is a next marker. Use that next marker's frame position as the last frame of this sequence.
+            frame_max = sorted_timeline_markers[next_marker_index].frame
+            if options.should_trim_timeline_marker_sequences:
+                nla_strips = get_nla_strips_in_timeframe(animation_data, marker.frame, frame_max)
+                if len(nla_strips) > 0:
+                    frame_max = min(frame_max, max(map(lambda nla_strip: nla_strip.frame_end, nla_strips)))
+                    frame_min = max(frame_min, min(map(lambda nla_strip: nla_strip.frame_start, nla_strips)))
+                else:
+                    # No strips in between this marker and the next, just export this as a one-frame animation.
+                    frame_max = frame_min
+        else:
+            # There is no next marker.
+            # Find the final frame of all the NLA strips and use that as the last frame of this sequence.
+            for nla_track in animation_data.nla_tracks:
+                if nla_track.mute:
+                    continue
+                for strip in nla_track.strips:
+                    frame_max = max(frame_max, strip.frame_end)
+
+        if frame_min > frame_max:
+            continue
+
+        sequence_frame_ranges[marker_name] = int(frame_min), int(frame_max)
+
+    return sequence_frame_ranges
+
+
+def build_psa(context: bpy.types.Context, options: PsaBuildOptions) -> Psa:
+    active_object = context.view_layer.objects.active
+
+    if active_object.type != 'ARMATURE':
+        raise RuntimeError('Selected object must be an Armature')
+
+    if options.should_override_animation_data:
+        animation_data_object = options.animation_data_override
+    else:
+        animation_data_object = active_object
+
+    animation_data = animation_data_object.animation_data
+
+    if animation_data is None:
+        raise RuntimeError(f'No animation data for object \'{animation_data_object.name}\'')
+
+    # Ensure that we actually have items that we are going to be exporting.
+    if options.sequence_source == 'ACTIONS' and len(options.actions) == 0:
+        raise RuntimeError('No actions were selected for export')
+    elif options.sequence_source == 'TIMELINE_MARKERS' and len(options.marker_names) == 0:
+        raise RuntimeError('No timeline markers were selected for export')
+
+    psa = Psa()
+
+    armature_object = active_object
+    armature_data = typing.cast(Armature, armature_object.data)
+    bones: List[Bone] = list(iter(armature_data.bones))
+
+    # The order of the armature bones and the pose bones is not guaranteed to be the same.
+    # As a result, we need to reconstruct the list of pose bones in the same order as the
+    # armature bones.
+    bone_names = [x.name for x in bones]
+    pose_bones = [(bone_names.index(bone.name), bone) for bone in armature_object.pose.bones]
+    pose_bones.sort(key=lambda x: x[0])
+    pose_bones = [x[1] for x in pose_bones]
+
+    # Get a list of all the bone indices and instigator bones for the bone filter settings.
+    export_bone_names = get_export_bone_names(armature_object, options.bone_filter_mode, options.bone_group_indices)
+    bone_indices = [bone_names.index(x) for x in export_bone_names]
+
+    # Make the bone lists contain only the bones that are going to be exported.
+    bones = [bones[bone_index] for bone_index in bone_indices]
+    pose_bones = [pose_bones[bone_index] for bone_index in bone_indices]
+
+    # No bones are going to be exported.
+    if len(bones) == 0:
+        raise RuntimeError('No bones available for export')
+
+    # Check that all bone names are valid.
+    if not options.should_ignore_bone_name_restrictions:
+        check_bone_names(map(lambda bone: bone.name, bones))
+
+    # Build list of PSA bones.
+    for bone in bones:
+        psa_bone = Psa.Bone()
+        psa_bone.name = bytes(bone.name, encoding='windows-1252')
+
+        try:
+            parent_index = bones.index(bone.parent)
+            psa_bone.parent_index = parent_index
+            psa.bones[parent_index].children_count += 1
+        except ValueError:
+            psa_bone.parent_index = -1
+
+        if bone.parent is not None:
+            rotation = bone.matrix.to_quaternion().conjugated()
+            inverse_parent_rotation = bone.parent.matrix.to_quaternion().inverted()
+            parent_head = inverse_parent_rotation @ bone.parent.head
+            parent_tail = inverse_parent_rotation @ bone.parent.tail
+            location = (parent_tail - parent_head) + bone.head
+        else:
+            armature_local_matrix = armature_object.matrix_local
+            location = armature_local_matrix @ bone.head
+            bone_rotation = bone.matrix.to_quaternion().conjugated()
+            local_rotation = armature_local_matrix.to_3x3().to_quaternion().conjugated()
+            rotation = bone_rotation @ local_rotation
+            rotation.conjugate()
+
+        psa_bone.location.x = location.x
+        psa_bone.location.y = location.y
+        psa_bone.location.z = location.z
+
+        psa_bone.rotation.x = rotation.x
+        psa_bone.rotation.y = rotation.y
+        psa_bone.rotation.z = rotation.z
+        psa_bone.rotation.w = rotation.w
+
+        psa.bones.append(psa_bone)
+
+    # Populate the export sequence list.
+    class NlaState:
+        def __init__(self):
+            self.frame_min = 0
+            self.frame_max = 0
+            self.action = None
+
+    class ExportSequence:
+        def __init__(self):
+            self.name = ''
+            self.nla_state = NlaState()
+            self.fps = 30.0
+
+    export_sequences = []
+
+    if options.sequence_source == 'ACTIONS':
+        for action in options.actions:
+            if len(action.fcurves) == 0:
+                continue
+            export_sequence = ExportSequence()
+            export_sequence.nla_state.action = action
+            export_sequence.name = get_psa_sequence_name(action, options.should_use_original_sequence_names)
+            frame_min, frame_max = [int(x) for x in action.frame_range]
+            export_sequence.nla_state.frame_min = frame_min
+            export_sequence.nla_state.frame_max = frame_max
+            export_sequence.fps = get_sequence_fps(context, options, [action])
+            export_sequences.append(export_sequence)
+        pass
+    elif options.sequence_source == 'TIMELINE_MARKERS':
+        sequence_frame_ranges = get_timeline_marker_sequence_frame_ranges(animation_data, context, options)
+
+        for name, (frame_min, frame_max) in sequence_frame_ranges.items():
+            export_sequence = ExportSequence()
+            export_sequence.name = name
+            export_sequence.nla_state.action = None
+            export_sequence.nla_state.frame_min = frame_min
+            export_sequence.nla_state.frame_max = frame_max
+
+            nla_strips_actions = set(
+                map(lambda x: x.action, get_nla_strips_in_timeframe(animation_data, frame_min, frame_max)))
+            export_sequence.fps = get_sequence_fps(context, options, nla_strips_actions)
+            export_sequences.append(export_sequence)
+    else:
+        raise ValueError(f'Unhandled sequence source: {options.sequence_source}')
+
+    # Add prefixes and suffices to the names of the export sequences and strip whitespace.
+    for export_sequence in export_sequences:
+        export_sequence.name = f'{options.sequence_name_prefix}{export_sequence.name}{options.sequence_name_suffix}'
+        export_sequence.name = export_sequence.name.strip()
+
+    # Save the current action and frame so that we can restore the state once we are done.
+    saved_frame_current = context.scene.frame_current
+    saved_action = animation_data.action
+
+    # Now build the PSA sequences.
+    # We actually alter the timeline frame and simply record the resultant pose bone matrices.
+    frame_start_index = 0
+
+    for export_sequence in export_sequences:
+        # Link the action to the animation data and update view layer.
+        animation_data.action = export_sequence.nla_state.action
+        context.view_layer.update()
+
+        frame_min = export_sequence.nla_state.frame_min
+        frame_max = export_sequence.nla_state.frame_max
+        frame_count = frame_max - frame_min + 1
+
+        psa_sequence = Psa.Sequence()
+        psa_sequence.name = bytes(export_sequence.name, encoding='windows-1252')
+        psa_sequence.frame_count = frame_count
+        psa_sequence.frame_start_index = frame_start_index
+        psa_sequence.fps = export_sequence.fps
+
+        for frame in range(frame_count):
+            context.scene.frame_set(frame_min + frame)
+
+            for pose_bone in pose_bones:
+                key = Psa.Key()
+
+                if pose_bone.parent is not None:
+                    pose_bone_matrix = pose_bone.matrix
+                    pose_bone_parent_matrix = pose_bone.parent.matrix
+                    pose_bone_matrix = pose_bone_parent_matrix.inverted() @ pose_bone_matrix
+                else:
+                    if options.root_motion:
+                        # Export root motion
+                        pose_bone_matrix = armature_object.matrix_world @ pose_bone.matrix
+                    else:
+                        pose_bone_matrix = pose_bone.matrix
+
+                location = pose_bone_matrix.to_translation()
+                rotation = pose_bone_matrix.to_quaternion().normalized()
+
+                if pose_bone.parent is not None:
+                    rotation.conjugate()
+
+                key.location.x = location.x
+                key.location.y = location.y
+                key.location.z = location.z
+                key.rotation.x = rotation.x
+                key.rotation.y = rotation.y
+                key.rotation.z = rotation.z
+                key.rotation.w = rotation.w
+                key.time = 1.0 / psa_sequence.fps
+
+                psa.keys.append(key)
+
+            psa_sequence.bone_count = len(pose_bones)
+            psa_sequence.track_time = frame_count
+
+        frame_start_index += frame_count
+
+        psa.sequences[export_sequence.name] = psa_sequence
+
+    # Restore the previous action & frame.
+    animation_data.action = saved_action
+    context.scene.frame_set(saved_frame_current)
+
+    return psa

io_scene_psk_psa/psa/data.py

@@ -1,9 +1,16 @@
+import typing
+from collections import OrderedDict
 from typing import List
+
 from ..data import *
 
+"""
+Note that keys are not stored within the Psa object.
+Use the PsaReader::get_sequence_keys to get the keys for a sequence.
+"""
+
 
 class Psa(object):
-
     class Bone(Structure):
         _fields_ = [
             ('name', c_char * 64),
@@ -22,7 +29,7 @@ class Psa(object):
             ('bone_count', c_int32),
             ('root_include', c_int32),
             ('compression_style', c_int32),
-            ('key_quotum', c_int32),  # what the fuck is a quotum
+            ('key_quotum', c_int32),
             ('key_reduction', c_float),
             ('track_time', c_float),
             ('fps', c_float),
@@ -38,7 +45,20 @@ class Psa(object):
             ('time', c_float)
         ]
 
+        @property
+        def data(self):
+            yield self.rotation.w
+            yield self.rotation.x
+            yield self.rotation.y
+            yield self.rotation.z
+            yield self.location.x
+            yield self.location.y
+            yield self.location.z
+
+        def __repr__(self) -> str:
+            return repr((self.location, self.rotation, self.time))
+
     def __init__(self):
         self.bones: List[Psa.Bone] = []
-        self.sequences: List[Psa.Sequence] = []
+        self.sequences: typing.OrderedDict[str, Psa.Sequence] = OrderedDict()
         self.keys: List[Psa.Key] = []

io_scene_psk_psa/psa/exporter.py

@@ -0,0 +1,547 @@
+import fnmatch
+import sys
+from typing import Type
+
+import bpy
+from bpy.props import BoolProperty, CollectionProperty, EnumProperty, FloatProperty, IntProperty, PointerProperty, \
+    StringProperty
+from bpy.types import Action, Operator, PropertyGroup, UIList
+from bpy_extras.io_utils import ExportHelper
+
+from .builder import PsaBuildOptions, build_psa
+from .data import *
+from ..helpers import *
+from ..types import BoneGroupListItem
+
+
+def write_section(fp, name: bytes, data_type: Type[Structure] = None, data: list = None):
+    section = Section()
+    section.name = name
+    if data_type is not None and data is not None:
+        section.data_size = sizeof(data_type)
+        section.data_count = len(data)
+    fp.write(section)
+    if data is not None:
+        for datum in data:
+            fp.write(datum)
+
+
+def export_psa(psa: Psa, path: str):
+    with open(path, 'wb') as fp:
+        write_section(fp, b'ANIMHEAD')
+        write_section(fp, b'BONENAMES', Psa.Bone, psa.bones)
+        write_section(fp, b'ANIMINFO', Psa.Sequence, list(psa.sequences.values()))
+        write_section(fp, b'ANIMKEYS', Psa.Key, psa.keys)
+
+
+class PsaExportActionListItem(PropertyGroup):
+    action: PointerProperty(type=Action)
+    name: StringProperty()
+    is_selected: BoolProperty(default=False)
+
+
+class PsaExportTimelineMarkerListItem(PropertyGroup):
+    marker_index: IntProperty()
+    name: StringProperty()
+    is_selected: BoolProperty(default=True)
+
+
+def update_action_names(context):
+    pg = context.scene.psa_export
+    for item in pg.action_list:
+        action = item.action
+        item.action_name = get_psa_sequence_name(action, pg.should_use_original_sequence_names)
+
+
+def should_use_original_sequence_names_updated(_, context):
+    update_action_names(context)
+
+
+def psa_export_property_group_animation_data_override_poll(_context, obj):
+    return obj.animation_data is not None
+
+
+empty_set = set()
+
+
+class PsaExportPropertyGroup(PropertyGroup):
+    root_motion: BoolProperty(
+        name='Root Motion',
+        options=empty_set,
+        default=False,
+        description='The root bone will be transformed as it appears in the scene',
+    )
+    should_override_animation_data: BoolProperty(
+        name='Override Animation Data',
+        options=empty_set,
+        default=False,
+        description='Use the animation data from a different object instead of the selected object'
+    )
+    animation_data_override: PointerProperty(
+        type=bpy.types.Object,
+        poll=psa_export_property_group_animation_data_override_poll
+    )
+    sequence_source: EnumProperty(
+        name='Source',
+        options=empty_set,
+        description='',
+        items=(
+            ('ACTIONS', 'Actions', 'Sequences will be exported using actions', 'ACTION', 0),
+            ('TIMELINE_MARKERS', 'Timeline Markers', 'Sequences will be exported using timeline markers', 'MARKER_HLT',
+             1),
+        )
+    )
+    fps_source: EnumProperty(
+        name='FPS Source',
+        options=empty_set,
+        description='',
+        items=(
+            ('SCENE', 'Scene', '', 'SCENE_DATA', 0),
+            ('ACTION_METADATA', 'Action Metadata',
+             'The frame rate will be determined by action\'s "psa_sequence_fps" custom property, if it exists. If the Sequence Source is Timeline Markers, the lowest value of all contributing actions will be used. If no metadata is available, the scene\'s frame rate will be used.',
+             'PROPERTIES', 1),
+            ('CUSTOM', 'Custom', '', 2)
+        )
+    )
+    fps_custom: FloatProperty(default=30.0, min=sys.float_info.epsilon, soft_min=1.0, options=empty_set, step=100,
+                              soft_max=60.0)
+    action_list: CollectionProperty(type=PsaExportActionListItem)
+    action_list_index: IntProperty(default=0)
+    marker_list: CollectionProperty(type=PsaExportTimelineMarkerListItem)
+    marker_list_index: IntProperty(default=0)
+    bone_filter_mode: EnumProperty(
+        name='Bone Filter',
+        options=empty_set,
+        description='',
+        items=(
+            ('ALL', 'All', 'All bones will be exported.'),
+            ('BONE_GROUPS', 'Bone Groups', 'Only bones belonging to the selected bone groups and their ancestors will '
+                                           'be exported.'),
+        )
+    )
+    bone_group_list: CollectionProperty(type=BoneGroupListItem)
+    bone_group_list_index: IntProperty(default=0, name='', description='')
+    should_use_original_sequence_names: BoolProperty(
+        default=False,
+        name='Original Names',
+        options=empty_set,
+        update=should_use_original_sequence_names_updated,
+        description='If the action was imported from the PSA Import panel, the original name of the sequence will be '
+                    'used instead of the Blender action name',
+    )
+    should_trim_timeline_marker_sequences: BoolProperty(
+        default=True,
+        name='Trim Sequences',
+        options=empty_set,
+        description='Frames without NLA track information at the boundaries of timeline markers will be excluded from '
+                    'the exported sequences '
+    )
+    should_ignore_bone_name_restrictions: BoolProperty(
+        default=False,
+        name='Ignore Bone Name Restrictions',
+        description='Bone names restrictions will be ignored. Note that bone names without properly formatted names '
+                    'cannot be referenced in scripts.'
+    )
+    sequence_name_prefix: StringProperty(name='Prefix', options=empty_set)
+    sequence_name_suffix: StringProperty(name='Suffix', options=empty_set)
+    sequence_filter_name: StringProperty(
+        default='',
+        name='Filter by Name',
+        options={'TEXTEDIT_UPDATE'},
+        description='Only show items matching this name (use \'*\' as wildcard)')
+    sequence_use_filter_invert: BoolProperty(
+        default=False,
+        name='Invert',
+        options=empty_set,
+        description='Invert filtering (show hidden items, and vice versa)')
+    sequence_filter_asset: BoolProperty(
+        default=False,
+        name='Show assets',
+        options=empty_set,
+        description='Show actions that belong to an asset library')
+    sequence_use_filter_sort_reverse: BoolProperty(default=True, options=empty_set)
+
+
+def is_bone_filter_mode_item_available(context, identifier):
+    if identifier == 'BONE_GROUPS':
+        obj = context.active_object
+        if not obj.pose or not obj.pose.bone_groups:
+            return False
+    return True
+
+
+class PsaExportOperator(Operator, ExportHelper):
+    bl_idname = 'psa_export.operator'
+    bl_label = 'Export'
+    bl_options = {'INTERNAL', 'UNDO'}
+    __doc__ = 'Export actions to PSA'
+    filename_ext = '.psa'
+    filter_glob: StringProperty(default='*.psa', options={'HIDDEN'})
+    filepath: StringProperty(
+        name='File Path',
+        description='File path used for exporting the PSA file',
+        maxlen=1024,
+        default='')
+
+    def __init__(self):
+        self.armature = None
+
+    @classmethod
+    def poll(cls, context):
+        try:
+            cls._check_context(context)
+        except RuntimeError as e:
+            cls.poll_message_set(str(e))
+            return False
+        return True
+
+    def draw(self, context):
+        layout = self.layout
+        pg = getattr(context.scene, 'psa_export')
+
+        # FPS
+        layout.prop(pg, 'fps_source', text='FPS')
+        if pg.fps_source == 'CUSTOM':
+            layout.prop(pg, 'fps_custom', text='Custom')
+
+        # SOURCE
+        layout.prop(pg, 'sequence_source', text='Source')
+
+        if pg.sequence_source == 'TIMELINE_MARKERS':
+            # ANIMDATA SOURCE
+            layout.prop(pg, 'should_override_animation_data')
+            if pg.should_override_animation_data:
+                layout.prop(pg, 'animation_data_override', text='')
+
+        # SELECT ALL/NONE
+        row = layout.row(align=True)
+        row.label(text='Select')
+        row.operator(PsaExportActionsSelectAll.bl_idname, text='All', icon='CHECKBOX_HLT')
+        row.operator(PsaExportActionsDeselectAll.bl_idname, text='None', icon='CHECKBOX_DEHLT')
+
+        # ACTIONS
+        if pg.sequence_source == 'ACTIONS':
+            rows = max(3, min(len(pg.action_list), 10))
+
+            layout.template_list('PSA_UL_ExportSequenceList', '', pg, 'action_list', pg, 'action_list_index', rows=rows)
+
+            col = layout.column()
+            col.use_property_split = True
+            col.use_property_decorate = False
+            col.prop(pg, 'should_use_original_sequence_names')
+            col.prop(pg, 'sequence_name_prefix')
+            col.prop(pg, 'sequence_name_suffix')
+
+        elif pg.sequence_source == 'TIMELINE_MARKERS':
+            rows = max(3, min(len(pg.marker_list), 10))
+            layout.template_list('PSA_UL_ExportSequenceList', '', pg, 'marker_list', pg, 'marker_list_index',
+                                 rows=rows)
+
+            col = layout.column()
+            col.use_property_split = True
+            col.use_property_decorate = False
+            col.prop(pg, 'should_trim_timeline_marker_sequences')
+            col.prop(pg, 'sequence_name_prefix')
+            col.prop(pg, 'sequence_name_suffix')
+
+        # Determine if there is going to be a naming conflict and display an error, if so.
+        selected_items = [x for x in pg.action_list if x.is_selected]
+        action_names = [x.name for x in selected_items]
+        action_name_counts = Counter(action_names)
+        for action_name, count in action_name_counts.items():
+            if count > 1:
+                layout.label(text=f'Duplicate action: {action_name}', icon='ERROR')
+                break
+
+        layout.separator()
+
+        # BONES
+        row = layout.row(align=True)
+        row.prop(pg, 'bone_filter_mode', text='Bones')
+
+        if pg.bone_filter_mode == 'BONE_GROUPS':
+            row = layout.row(align=True)
+            row.label(text='Select')
+            row.operator(PsaExportBoneGroupsSelectAll.bl_idname, text='All', icon='CHECKBOX_HLT')
+            row.operator(PsaExportBoneGroupsDeselectAll.bl_idname, text='None', icon='CHECKBOX_DEHLT')
+            rows = max(3, min(len(pg.bone_group_list), 10))
+            layout.template_list('PSX_UL_BoneGroupList', '', pg, 'bone_group_list', pg, 'bone_group_list_index',
+                                 rows=rows)
+
+        layout.prop(pg, 'should_ignore_bone_name_restrictions')
+
+        layout.separator()
+
+        # ROOT MOTION
+        layout.prop(pg, 'root_motion', text='Root Motion')
+
+    def is_action_for_armature(self, action):
+        if len(action.fcurves) == 0:
+            return False
+        bone_names = set([x.name for x in self.armature.data.bones])
+        for fcurve in action.fcurves:
+            match = re.match(r'pose\.bones\[\"([^\"]+)\"](\[\"([^\"]+)\"])?', fcurve.data_path)
+            if not match:
+                continue
+            bone_name = match.group(1)
+            if bone_name in bone_names:
+                return True
+        return False
+
+    @classmethod
+    def _check_context(cls, context):
+        if context.view_layer.objects.active is None:
+            raise RuntimeError('An armature must be selected')
+
+        if context.view_layer.objects.active.type != 'ARMATURE':
+            raise RuntimeError('The selected object must be an armature')
+
+    def invoke(self, context, _event):
+        try:
+            self._check_context(context)
+        except RuntimeError as e:
+            self.report({'ERROR_INVALID_CONTEXT'}, str(e))
+
+        pg = getattr(context.scene, 'psa_export')
+        self.armature = context.view_layer.objects.active
+
+        # Populate actions list.
+        pg.action_list.clear()
+        for action in bpy.data.actions:
+            if not self.is_action_for_armature(action):
+                continue
+            item = pg.action_list.add()
+            item.action = action
+            item.name = action.name
+            item.is_selected = False
+
+        update_action_names(context)
+
+        # Populate timeline markers list.
+        pg.marker_list.clear()
+        for marker in context.scene.timeline_markers:
+            item = pg.marker_list.add()
+            item.name = marker.name
+            item.is_selected = False
+
+        if len(pg.action_list) == 0 and len(pg.marker_list) == 0:
+            # If there are no actions at all, we have nothing to export, so just cancel the operation.
+            self.report({'ERROR_INVALID_CONTEXT'}, 'There are no actions or timeline markers to export.')
+            return {'CANCELLED'}
+
+        # Populate bone groups list.
+        populate_bone_group_list(self.armature, pg.bone_group_list)
+
+        context.window_manager.fileselect_add(self)
+
+        return {'RUNNING_MODAL'}
+
+    def execute(self, context):
+        pg = getattr(context.scene, 'psa_export')
+
+        actions = [x.action for x in pg.action_list if x.is_selected]
+        marker_names = [x.name for x in pg.marker_list if x.is_selected]
+
+        options = PsaBuildOptions()
+        options.should_override_animation_data = pg.should_override_animation_data
+        options.animation_data_override = pg.animation_data_override
+        options.fps_source = pg.fps_source
+        options.fps_custom = pg.fps_custom
+        options.sequence_source = pg.sequence_source
+        options.actions = actions
+        options.marker_names = marker_names
+        options.bone_filter_mode = pg.bone_filter_mode
+        options.bone_group_indices = [x.index for x in pg.bone_group_list if x.is_selected]
+        options.should_use_original_sequence_names = pg.should_use_original_sequence_names
+        options.should_trim_timeline_marker_sequences = pg.should_trim_timeline_marker_sequences
+        options.should_ignore_bone_name_restrictions = pg.should_ignore_bone_name_restrictions
+        options.sequence_name_prefix = pg.sequence_name_prefix
+        options.sequence_name_suffix = pg.sequence_name_suffix
+        options.root_motion = pg.root_motion
+
+        try:
+            psa = build_psa(context, options)
+            self.report({'INFO'}, f'PSA export successful')
+        except RuntimeError as e:
+            self.report({'ERROR_INVALID_CONTEXT'}, str(e))
+            return {'CANCELLED'}
+
+        export_psa(psa, self.filepath)
+
+        return {'FINISHED'}
+
+
+def filter_sequences(pg: PsaExportPropertyGroup, sequences) -> List[int]:
+    bitflag_filter_item = 1 << 30
+    flt_flags = [bitflag_filter_item] * len(sequences)
+
+    if pg.sequence_filter_name:
+        # Filter name is non-empty.
+        for i, sequence in enumerate(sequences):
+            if not fnmatch.fnmatch(sequence.name, f'*{pg.sequence_filter_name}*'):
+                flt_flags[i] &= ~bitflag_filter_item
+
+        # Invert filter flags for all items.
+        if pg.sequence_use_filter_invert:
+            for i, sequence in enumerate(sequences):
+                flt_flags[i] ^= bitflag_filter_item
+
+    if not pg.sequence_filter_asset:
+        for i, sequence in enumerate(sequences):
+            if hasattr(sequence, 'action') and sequence.action.asset_data is not None:
+                flt_flags[i] &= ~bitflag_filter_item
+
+    return flt_flags
+
+
+def get_visible_sequences(pg: PsaExportPropertyGroup, sequences) -> List[PsaExportActionListItem]:
+    visible_sequences = []
+    for i, flag in enumerate(filter_sequences(pg, sequences)):
+        if bool(flag & (1 << 30)):
+            visible_sequences.append(sequences[i])
+    return visible_sequences
+
+
+class PSA_UL_ExportSequenceList(UIList):
+
+    def __init__(self):
+        super(PSA_UL_ExportSequenceList, self).__init__()
+        # Show the filtering options by default.
+        self.use_filter_show = True
+
+    def draw_item(self, context, layout, data, item, icon, active_data, active_propname, index):
+        layout.prop(item, 'is_selected', icon_only=True, text=item.name)
+        if hasattr(item, 'action') and item.action.asset_data is not None:
+            layout.label(text='', icon='ASSET_MANAGER')
+
+    def draw_filter(self, context, layout):
+        pg = getattr(context.scene, 'psa_export')
+        row = layout.row()
+        subrow = row.row(align=True)
+        subrow.prop(pg, 'sequence_filter_name', text="")
+        subrow.prop(pg, 'sequence_use_filter_invert', text="", icon='ARROW_LEFTRIGHT')
+        # subrow.prop(pg, 'sequence_use_filter_sort_reverse', text='', icon='SORT_ASC')
+
+        if pg.sequence_source == 'ACTIONS':
+            subrow = row.row(align=True)
+            subrow.prop(pg, 'sequence_filter_asset', icon_only=True, icon='ASSET_MANAGER')
+
+    def filter_items(self, context, data, prop):
+        pg = getattr(context.scene, 'psa_export')
+        actions = getattr(data, prop)
+        flt_flags = filter_sequences(pg, actions)
+        flt_neworder = bpy.types.UI_UL_list.sort_items_by_name(actions, 'name')
+        return flt_flags, flt_neworder
+
+
+class PsaExportActionsSelectAll(Operator):
+    bl_idname = 'psa_export.sequences_select_all'
+    bl_label = 'Select All'
+    bl_description = 'Select all visible sequences'
+    bl_options = {'INTERNAL'}
+
+    @classmethod
+    def get_item_list(cls, context):
+        pg = context.scene.psa_export
+        if pg.sequence_source == 'ACTIONS':
+            return pg.action_list
+        elif pg.sequence_source == 'TIMELINE_MARKERS':
+            return pg.marker_list
+        return None
+
+    @classmethod
+    def poll(cls, context):
+        pg = getattr(context.scene, 'psa_export')
+        item_list = cls.get_item_list(context)
+        visible_sequences = get_visible_sequences(pg, item_list)
+        has_unselected_sequences = any(map(lambda item: not item.is_selected, visible_sequences))
+        return has_unselected_sequences
+
+    def execute(self, context):
+        pg = getattr(context.scene, 'psa_export')
+        sequences = self.get_item_list(context)
+        for sequence in get_visible_sequences(pg, sequences):
+            sequence.is_selected = True
+        return {'FINISHED'}
+
+
+class PsaExportActionsDeselectAll(Operator):
+    bl_idname = 'psa_export.sequences_deselect_all'
+    bl_label = 'Deselect All'
+    bl_description = 'Deselect all visible sequences'
+    bl_options = {'INTERNAL'}
+
+    @classmethod
+    def get_item_list(cls, context):
+        pg = context.scene.psa_export
+        if pg.sequence_source == 'ACTIONS':
+            return pg.action_list
+        elif pg.sequence_source == 'TIMELINE_MARKERS':
+            return pg.marker_list
+        return None
+
+    @classmethod
+    def poll(cls, context):
+        item_list = cls.get_item_list(context)
+        has_selected_items = any(map(lambda item: item.is_selected, item_list))
+        return len(item_list) > 0 and has_selected_items
+
+    def execute(self, context):
+        pg = getattr(context.scene, 'psa_export')
+        item_list = self.get_item_list(context)
+        for sequence in get_visible_sequences(pg, item_list):
+            sequence.is_selected = False
+        return {'FINISHED'}
+
+
+class PsaExportBoneGroupsSelectAll(Operator):
+    bl_idname = 'psa_export.bone_groups_select_all'
+    bl_label = 'Select All'
+    bl_description = 'Select all bone groups'
+    bl_options = {'INTERNAL'}
+
+    @classmethod
+    def poll(cls, context):
+        pg = getattr(context.scene, 'psa_export')
+        item_list = pg.bone_group_list
+        has_unselected_items = any(map(lambda action: not action.is_selected, item_list))
+        return len(item_list) > 0 and has_unselected_items
+
+    def execute(self, context):
+        pg = getattr(context.scene, 'psa_export')
+        for item in pg.bone_group_list:
+            item.is_selected = True
+        return {'FINISHED'}
+
+
+class PsaExportBoneGroupsDeselectAll(Operator):
+    bl_idname = 'psa_export.bone_groups_deselect_all'
+    bl_label = 'Deselect All'
+    bl_description = 'Deselect all bone groups'
+    bl_options = {'INTERNAL'}
+
+    @classmethod
+    def poll(cls, context):
+        pg = getattr(context.scene, 'psa_export')
+        item_list = pg.bone_group_list
+        has_selected_actions = any(map(lambda action: action.is_selected, item_list))
+        return len(item_list) > 0 and has_selected_actions
+
+    def execute(self, context):
+        pg = getattr(context.scene, 'psa_export')
+        for action in pg.bone_group_list:
+            action.is_selected = False
+        return {'FINISHED'}
+
+
+classes = (
+    PsaExportActionListItem,
+    PsaExportTimelineMarkerListItem,
+    PsaExportPropertyGroup,
+    PsaExportOperator,
+    PSA_UL_ExportSequenceList,
+    PsaExportActionsSelectAll,
+    PsaExportActionsDeselectAll,
+    PsaExportBoneGroupsSelectAll,
+    PsaExportBoneGroupsDeselectAll,
+)

io_scene_psk_psa/psa/importer.py

@@ -0,0 +1,689 @@
+import fnmatch
+import os
+import re
+import typing
+from collections import Counter
+from typing import List, Optional
+
+import bpy
+import numpy
+from bpy.props import StringProperty, BoolProperty, CollectionProperty, PointerProperty, IntProperty, EnumProperty
+from bpy.types import Operator, UIList, PropertyGroup, Panel, FCurve
+from bpy_extras.io_utils import ImportHelper
+from mathutils import Vector, Quaternion
+
+from .data import Psa
+from .reader import PsaReader
+
+
+class PsaImportOptions(object):
+    def __init__(self):
+        self.should_use_fake_user = False
+        self.should_stash = False
+        self.sequence_names = []
+        self.should_overwrite = False
+        self.should_write_keyframes = True
+        self.should_write_metadata = True
+        self.action_name_prefix = ''
+        self.should_convert_to_samples = False
+        self.bone_mapping_mode = 'CASE_INSENSITIVE'
+
+
+class ImportBone(object):
+    def __init__(self, psa_bone: Psa.Bone):
+        self.psa_bone: Psa.Bone = psa_bone
+        self.parent: Optional[ImportBone] = None
+        self.armature_bone = None
+        self.pose_bone = None
+        self.orig_loc: Vector = Vector()
+        self.orig_quat: Quaternion = Quaternion()
+        self.post_quat: Quaternion = Quaternion()
+        self.fcurves: List[FCurve] = []
+
+
+def calculate_fcurve_data(import_bone: ImportBone, key_data: typing.Iterable[float]):
+    # Convert world-space transforms to local-space transforms.
+    key_rotation = Quaternion(key_data[0:4])
+    key_location = Vector(key_data[4:])
+    q = import_bone.post_quat.copy()
+    q.rotate(import_bone.orig_quat)
+    quat = q
+    q = import_bone.post_quat.copy()
+    if import_bone.parent is None:
+        q.rotate(key_rotation.conjugated())
+    else:
+        q.rotate(key_rotation)
+    quat.rotate(q.conjugated())
+    loc = key_location - import_bone.orig_loc
+    loc.rotate(import_bone.post_quat.conjugated())
+    return quat.w, quat.x, quat.y, quat.z, loc.x, loc.y, loc.z
+
+
+class PsaImportResult:
+    def __init__(self):
+        self.warnings: List[str] = []
+
+
+def import_psa(psa_reader: PsaReader, armature_object: bpy.types.Object, options: PsaImportOptions) -> PsaImportResult:
+    result = PsaImportResult()
+    sequences = map(lambda x: psa_reader.sequences[x], options.sequence_names)
+    armature_data = typing.cast(bpy.types.Armature, armature_object.data)
+
+    # Create an index mapping from bones in the PSA to bones in the target armature.
+    psa_to_armature_bone_indices = {}
+    armature_bone_names = [x.name for x in armature_data.bones]
+    psa_bone_names = []
+    for psa_bone_index, psa_bone in enumerate(psa_reader.bones):
+        psa_bone_name: str = psa_bone.name.decode('windows-1252')
+        try:
+            psa_to_armature_bone_indices[psa_bone_index] = armature_bone_names.index(psa_bone_name)
+        except ValueError:
+            # PSA bone could not be mapped directly to an armature bone by name.
+            # Attempt to create a bone mapping by ignoring the case of the names.
+            if options.bone_mapping_mode == 'CASE_INSENSITIVE':
+                for armature_bone_index, armature_bone_name in enumerate(armature_bone_names):
+                    if armature_bone_name.upper() == psa_bone_name.upper():
+                        psa_to_armature_bone_indices[psa_bone_index] = armature_bone_index
+                        psa_bone_name = armature_bone_name
+                        break
+        psa_bone_names.append(psa_bone_name)
+
+    # Remove ambiguous bone mappings (where multiple PSA bones correspond to the same armature bone).
+    armature_bone_index_counts = Counter(psa_to_armature_bone_indices.values())
+    for armature_bone_index, count in armature_bone_index_counts.items():
+        if count > 1:
+            psa_bone_indices = []
+            for psa_bone_index, mapped_bone_index in psa_to_armature_bone_indices:
+                if mapped_bone_index == armature_bone_index:
+                    psa_bone_indices.append(psa_bone_index)
+            ambiguous_psa_bone_names = list(sorted([psa_bone_names[x] for x in psa_bone_indices]))
+            result.warnings.append(
+                f'Ambiguous mapping for bone {armature_bone_names[armature_bone_index]}!\n'
+                f'The following PSA bones all map to the same armature bone: {ambiguous_psa_bone_names}\n'
+                f'These bones will be ignored.'
+            )
+
+    # Report if there are missing bones in the target armature.
+    missing_bone_names = set(psa_bone_names).difference(set(armature_bone_names))
+    if len(missing_bone_names) > 0:
+        result.warnings.append(
+            f'The armature \'{armature_object.name}\' is missing {len(missing_bone_names)} bones that exist in '
+            'the PSA:\n' +
+            str(list(sorted(missing_bone_names)))
+        )
+    del armature_bone_names
+
+    # Create intermediate bone data for import operations.
+    import_bones = []
+    import_bones_dict = dict()
+
+    for (psa_bone_index, psa_bone), psa_bone_name in zip(enumerate(psa_reader.bones), psa_bone_names):
+        if psa_bone_index not in psa_to_armature_bone_indices:
+            # PSA bone does not map to armature bone, skip it and leave an empty bone in its place.
+            import_bones.append(None)
+            continue
+        import_bone = ImportBone(psa_bone)
+        import_bone.armature_bone = armature_data.bones[psa_bone_name]
+        import_bone.pose_bone = armature_object.pose.bones[psa_bone_name]
+        import_bones_dict[psa_bone_name] = import_bone
+        import_bones.append(import_bone)
+
+    for import_bone in filter(lambda x: x is not None, import_bones):
+        armature_bone = import_bone.armature_bone
+        if armature_bone.parent is not None and armature_bone.parent.name in psa_bone_names:
+            import_bone.parent = import_bones_dict[armature_bone.parent.name]
+        # Calculate the original location & rotation of each bone (in world-space maybe?)
+        if armature_bone.get('orig_quat') is not None:
+            # TODO: ideally we don't rely on bone auxiliary data like this, the non-aux data path is incorrect
+            # (animations are flipped 180 around Z)
+            import_bone.orig_quat = Quaternion(armature_bone['orig_quat'])
+            import_bone.orig_loc = Vector(armature_bone['orig_loc'])
+            import_bone.post_quat = Quaternion(armature_bone['post_quat'])
+        else:
+            if import_bone.parent is not None:
+                import_bone.orig_loc = armature_bone.matrix_local.translation - armature_bone.parent.matrix_local.translation
+                import_bone.orig_loc.rotate(armature_bone.parent.matrix_local.to_quaternion().conjugated())
+                import_bone.orig_quat = armature_bone.matrix_local.to_quaternion()
+                import_bone.orig_quat.rotate(armature_bone.parent.matrix_local.to_quaternion().conjugated())
+                import_bone.orig_quat.conjugate()
+            else:
+                import_bone.orig_loc = armature_bone.matrix_local.translation.copy()
+                import_bone.orig_quat = armature_bone.matrix_local.to_quaternion()
+            import_bone.post_quat = import_bone.orig_quat.conjugated()
+
+    # Create and populate the data for new sequences.
+    actions = []
+    for sequence in sequences:
+        # Add the action.
+        sequence_name = sequence.name.decode('windows-1252')
+        action_name = options.action_name_prefix + sequence_name
+
+        if options.should_overwrite and action_name in bpy.data.actions:
+            action = bpy.data.actions[action_name]
+        else:
+            action = bpy.data.actions.new(name=action_name)
+
+        if options.should_write_keyframes:
+            # Remove existing f-curves (replace with action.fcurves.clear() in Blender 3.2)
+            while len(action.fcurves) > 0:
+                action.fcurves.remove(action.fcurves[-1])
+
+            # Create f-curves for the rotation and location of each bone.
+            for psa_bone_index, armature_bone_index in psa_to_armature_bone_indices.items():
+                import_bone = import_bones[psa_bone_index]
+                pose_bone = import_bone.pose_bone
+                rotation_data_path = pose_bone.path_from_id('rotation_quaternion')
+                location_data_path = pose_bone.path_from_id('location')
+                import_bone.fcurves = [
+                    action.fcurves.new(rotation_data_path, index=0, action_group=pose_bone.name),  # Qw
+                    action.fcurves.new(rotation_data_path, index=1, action_group=pose_bone.name),  # Qx
+                    action.fcurves.new(rotation_data_path, index=2, action_group=pose_bone.name),  # Qy
+                    action.fcurves.new(rotation_data_path, index=3, action_group=pose_bone.name),  # Qz
+                    action.fcurves.new(location_data_path, index=0, action_group=pose_bone.name),  # Lx
+                    action.fcurves.new(location_data_path, index=1, action_group=pose_bone.name),  # Ly
+                    action.fcurves.new(location_data_path, index=2, action_group=pose_bone.name),  # Lz
+                ]
+
+            # Read the sequence data matrix from the PSA.
+            sequence_data_matrix = psa_reader.read_sequence_data_matrix(sequence_name)
+
+            # Convert the sequence's data from world-space to local-space.
+            for bone_index, import_bone in enumerate(import_bones):
+                if import_bone is None:
+                    continue
+                for frame_index in range(sequence.frame_count):
+                    # This bone has writeable keyframes for this frame.
+                    key_data = sequence_data_matrix[frame_index, bone_index]
+                    # Calculate the local-space key data for the bone.
+                    sequence_data_matrix[frame_index, bone_index] = calculate_fcurve_data(import_bone, key_data)
+
+            # Write the keyframes out.
+            fcurve_data = numpy.zeros(2 * sequence.frame_count, dtype=float)
+            fcurve_data[0::2] = range(sequence.frame_count)
+            for bone_index, import_bone in enumerate(import_bones):
+                if import_bone is None:
+                    continue
+                for fcurve_index, fcurve in enumerate(import_bone.fcurves):
+                    fcurve_data[1::2] = sequence_data_matrix[:, bone_index, fcurve_index]
+                    fcurve.keyframe_points.add(sequence.frame_count)
+                    fcurve.keyframe_points.foreach_set('co', fcurve_data)
+
+            if options.should_convert_to_samples:
+                # Bake the curve to samples.
+                for fcurve in action.fcurves:
+                    fcurve.convert_to_samples(start=0, end=sequence.frame_count)
+
+        # Write meta-data.
+        if options.should_write_metadata:
+            action['psa_sequence_name'] = sequence_name
+            action['psa_sequence_fps'] = sequence.fps
+
+        action.use_fake_user = options.should_use_fake_user
+
+        actions.append(action)
+
+    # If the user specifies, store the new animations as strips on a non-contributing NLA track.
+    if options.should_stash:
+        if armature_object.animation_data is None:
+            armature_object.animation_data_create()
+        for action in actions:
+            nla_track = armature_object.animation_data.nla_tracks.new()
+            nla_track.name = action.name
+            nla_track.mute = True
+            nla_track.strips.new(name=action.name, start=0, action=action)
+
+    return result
+
+
+empty_set = set()
+
+
+class PsaImportActionListItem(PropertyGroup):
+    action_name: StringProperty(options=empty_set)
+    is_selected: BoolProperty(default=False, options=empty_set)
+
+
+def load_psa_file(context):
+    pg = context.scene.psa_import
+    pg.sequence_list.clear()
+    pg.psa.bones.clear()
+    pg.psa_error = ''
+    try:
+        # Read the file and populate the action list.
+        p = os.path.abspath(pg.psa_file_path)
+        psa_reader = PsaReader(p)
+        for sequence in psa_reader.sequences.values():
+            item = pg.sequence_list.add()
+            item.action_name = sequence.name.decode('windows-1252')
+        for psa_bone in psa_reader.bones:
+            item = pg.psa.bones.add()
+            item.bone_name = psa_bone.name.decode('windows-1252')
+    except Exception as e:
+        pg.psa_error = str(e)
+
+
+def on_psa_file_path_updated(property_, context):
+    load_psa_file(context)
+
+
+class PsaBonePropertyGroup(PropertyGroup):
+    bone_name: StringProperty(options=empty_set)
+
+
+class PsaDataPropertyGroup(PropertyGroup):
+    bones: CollectionProperty(type=PsaBonePropertyGroup)
+    sequence_count: IntProperty(default=0)
+
+
+class PsaImportPropertyGroup(PropertyGroup):
+    psa_file_path: StringProperty(default='', options=empty_set, update=on_psa_file_path_updated, name='PSA File Path')
+    psa_error: StringProperty(default='')
+    psa: PointerProperty(type=PsaDataPropertyGroup)
+    sequence_list: CollectionProperty(type=PsaImportActionListItem)
+    sequence_list_index: IntProperty(name='', default=0)
+    should_use_fake_user: BoolProperty(default=True, name='Fake User',
+                                       description='Assign each imported action a fake user so that the data block is '
+                                                   'saved even it has no users',
+                                       options=empty_set)
+    should_stash: BoolProperty(default=False, name='Stash',
+                               description='Stash each imported action as a strip on a new non-contributing NLA track',
+                               options=empty_set)
+    should_use_action_name_prefix: BoolProperty(default=False, name='Prefix Action Name', options=empty_set)
+    action_name_prefix: StringProperty(default='', name='Prefix', options=empty_set)
+    should_overwrite: BoolProperty(default=False, name='Reuse Existing Actions', options=empty_set,
+                                   description='If an action with a matching name already exists, the existing action '
+                                               'will have it\'s data overwritten instead of a new action being created')
+    should_write_keyframes: BoolProperty(default=True, name='Keyframes', options=empty_set)
+    should_write_metadata: BoolProperty(default=True, name='Metadata', options=empty_set,
+                                        description='Additional data will be written to the custom properties of the '
+                                                    'Action (e.g., frame rate)')
+    sequence_filter_name: StringProperty(default='', options={'TEXTEDIT_UPDATE'})
+    sequence_filter_is_selected: BoolProperty(default=False, options=empty_set, name='Only Show Selected',
+                                              description='Only show selected sequences')
+    sequence_use_filter_invert: BoolProperty(default=False, options=empty_set)
+    sequence_use_filter_regex: BoolProperty(default=False, name='Regular Expression',
+                                            description='Filter using regular expressions', options=empty_set)
+    select_text: PointerProperty(type=bpy.types.Text)
+    should_convert_to_samples: BoolProperty(
+        default=False,
+        name='Convert to Samples',
+        description='Convert keyframes to read-only samples. '
+                    'Recommended if you do not plan on editing the actions directly'
+    )
+    bone_mapping_mode: EnumProperty(
+        name='Bone Mapping',
+        options=empty_set,
+        description='The method by which bones from the incoming PSA file are mapped to the armature',
+        items=(
+            ('EXACT', 'Exact', 'Bone names must match exactly.', 'EXACT', 0),
+            ('CASE_INSENSITIVE', 'Case Insensitive', 'Bones names must match, ignoring case (e.g., the bone PSA bone '
+             '\'root\' can be mapped to the armature bone \'Root\')', 'CASE_INSENSITIVE', 1),
+        )
+    )
+
+
+def filter_sequences(pg: PsaImportPropertyGroup, sequences) -> List[int]:
+    bitflag_filter_item = 1 << 30
+    flt_flags = [bitflag_filter_item] * len(sequences)
+
+    if pg.sequence_filter_name is not None:
+        # Filter name is non-empty.
+        if pg.sequence_use_filter_regex:
+            # Use regular expression. If regex pattern doesn't compile, just ignore it.
+            try:
+                regex = re.compile(pg.sequence_filter_name)
+                for i, sequence in enumerate(sequences):
+                    if not regex.match(sequence.action_name):
+                        flt_flags[i] &= ~bitflag_filter_item
+            except re.error:
+                pass
+        else:
+            # User regular text matching.
+            for i, sequence in enumerate(sequences):
+                if not fnmatch.fnmatch(sequence.action_name, f'*{pg.sequence_filter_name}*'):
+                    flt_flags[i] &= ~bitflag_filter_item
+
+    if pg.sequence_filter_is_selected:
+        for i, sequence in enumerate(sequences):
+            if not sequence.is_selected:
+                flt_flags[i] &= ~bitflag_filter_item
+
+    if pg.sequence_use_filter_invert:
+        # Invert filter flags for all items.
+        for i, sequence in enumerate(sequences):
+            flt_flags[i] ^= bitflag_filter_item
+
+    return flt_flags
+
+
+def get_visible_sequences(pg: PsaImportPropertyGroup, sequences) -> List[PsaImportActionListItem]:
+    bitflag_filter_item = 1 << 30
+    visible_sequences = []
+    for i, flag in enumerate(filter_sequences(pg, sequences)):
+        if bool(flag & bitflag_filter_item):
+            visible_sequences.append(sequences[i])
+    return visible_sequences
+
+
+class PSA_UL_SequenceList(UIList):
+    def draw_item(self, context, layout, data, item, icon, active_data, active_property, index, flt_flag):
+        row = layout.row(align=True)
+        split = row.split(align=True, factor=0.75)
+        column = split.row(align=True)
+        column.alignment = 'LEFT'
+        column.prop(item, 'is_selected', icon_only=True)
+        column.label(text=getattr(item, 'action_name'))
+
+    def draw_filter(self, context, layout):
+        pg = getattr(context.scene, 'psa_import')
+        row = layout.row()
+        sub_row = row.row(align=True)
+        sub_row.prop(pg, 'sequence_filter_name', text="")
+        sub_row.prop(pg, 'sequence_use_filter_invert', text="", icon='ARROW_LEFTRIGHT')
+        sub_row.prop(pg, 'sequence_use_filter_regex', text="", icon='SORTBYEXT')
+        sub_row.prop(pg, 'sequence_filter_is_selected', text="", icon='CHECKBOX_HLT')
+
+    def filter_items(self, context, data, property_):
+        pg = getattr(context.scene, 'psa_import')
+        sequences = getattr(data, property_)
+        flt_flags = filter_sequences(pg, sequences)
+        flt_neworder = bpy.types.UI_UL_list.sort_items_by_name(sequences, 'action_name')
+        return flt_flags, flt_neworder
+
+
+class PSA_UL_ImportSequenceList(PSA_UL_SequenceList, UIList):
+    pass
+
+
+class PSA_UL_ImportActionList(PSA_UL_SequenceList, UIList):
+    pass
+
+
+class PsaImportSequencesFromText(Operator):
+    bl_idname = 'psa_import.sequences_select_from_text'
+    bl_label = 'Select By Text List'
+    bl_description = 'Select sequences by name from text list'
+    bl_options = {'INTERNAL', 'UNDO'}
+
+    @classmethod
+    def poll(cls, context):
+        pg = getattr(context.scene, 'psa_import')
+        return len(pg.sequence_list) > 0
+
+    def invoke(self, context, event):
+        return context.window_manager.invoke_props_dialog(self, width=256)
+
+    def draw(self, context):
+        layout = self.layout
+        pg = getattr(context.scene, 'psa_import')
+        layout.label(icon='INFO', text='Each sequence name should be on a new line.')
+        layout.prop(pg, 'select_text', text='')
+
+    def execute(self, context):
+        pg = getattr(context.scene, 'psa_import')
+        if pg.select_text is None:
+            self.report({'ERROR_INVALID_CONTEXT'}, 'No text block selected')
+            return {'CANCELLED'}
+        contents = pg.select_text.as_string()
+        count = 0
+        for line in contents.split('\n'):
+            for sequence in pg.sequence_list:
+                if sequence.action_name == line:
+                    sequence.is_selected = True
+                    count += 1
+        self.report({'INFO'}, f'Selected {count} sequence(s)')
+        return {'FINISHED'}
+
+
+class PsaImportSequencesSelectAll(Operator):
+    bl_idname = 'psa_import.sequences_select_all'
+    bl_label = 'All'
+    bl_description = 'Select all sequences'
+    bl_options = {'INTERNAL'}
+
+    @classmethod
+    def poll(cls, context):
+        pg = getattr(context.scene, 'psa_import')
+        visible_sequences = get_visible_sequences(pg, pg.sequence_list)
+        has_unselected_actions = any(map(lambda action: not action.is_selected, visible_sequences))
+        return len(visible_sequences) > 0 and has_unselected_actions
+
+    def execute(self, context):
+        pg = getattr(context.scene, 'psa_import')
+        visible_sequences = get_visible_sequences(pg, pg.sequence_list)
+        for sequence in visible_sequences:
+            sequence.is_selected = True
+        return {'FINISHED'}
+
+
+class PsaImportSequencesDeselectAll(Operator):
+    bl_idname = 'psa_import.sequences_deselect_all'
+    bl_label = 'None'
+    bl_description = 'Deselect all visible sequences'
+    bl_options = {'INTERNAL'}
+
+    @classmethod
+    def poll(cls, context):
+        pg = getattr(context.scene, 'psa_import')
+        visible_sequences = get_visible_sequences(pg, pg.sequence_list)
+        has_selected_sequences = any(map(lambda sequence: sequence.is_selected, visible_sequences))
+        return len(visible_sequences) > 0 and has_selected_sequences
+
+    def execute(self, context):
+        pg = getattr(context.scene, 'psa_import')
+        visible_sequences = get_visible_sequences(pg, pg.sequence_list)
+        for sequence in visible_sequences:
+            sequence.is_selected = False
+        return {'FINISHED'}
+
+
+class PSA_PT_ImportPanel_Advanced(Panel):
+    bl_space_type = 'PROPERTIES'
+    bl_region_type = 'WINDOW'
+    bl_label = 'Advanced'
+    bl_options = {'DEFAULT_CLOSED'}
+    bl_parent_id = 'PSA_PT_ImportPanel'
+
+    def draw(self, context):
+        layout = self.layout
+        pg = getattr(context.scene, 'psa_import')
+
+        col = layout.column()
+        col.use_property_split = True
+        col.use_property_decorate = False
+        col.prop(pg, 'bone_mapping_mode')
+
+        if pg.should_write_keyframes:
+            col = layout.column(heading='Keyframes')
+            col.use_property_split = True
+            col.use_property_decorate = False
+            col.prop(pg, 'should_convert_to_samples')
+            col.separator()
+
+        col = layout.column(heading='Options')
+        col.use_property_split = True
+        col.use_property_decorate = False
+        col.prop(pg, 'should_use_fake_user')
+        col.prop(pg, 'should_stash')
+        col.prop(pg, 'should_use_action_name_prefix')
+
+        if pg.should_use_action_name_prefix:
+            col.prop(pg, 'action_name_prefix')
+
+
+class PSA_PT_ImportPanel(Panel):
+    bl_space_type = 'PROPERTIES'
+    bl_region_type = 'WINDOW'
+    bl_label = 'PSA Import'
+    bl_context = 'data'
+    bl_category = 'PSA Import'
+    bl_options = {'DEFAULT_CLOSED'}
+
+    @classmethod
+    def poll(cls, context):
+        return context.view_layer.objects.active.type == 'ARMATURE'
+
+    def draw(self, context):
+        layout = self.layout
+        pg = getattr(context.scene, 'psa_import')
+
+        row = layout.row(align=True)
+        row.operator(PsaImportSelectFile.bl_idname, text='', icon='FILEBROWSER')
+        row.prop(pg, 'psa_file_path', text='')
+        row.operator(PsaImportFileReload.bl_idname, text='', icon='FILE_REFRESH')
+
+        if pg.psa_error != '':
+            row = layout.row()
+            row.label(text='File could not be read', icon='ERROR')
+
+        box = layout.box()
+
+        box.label(text=f'Sequences ({len(pg.sequence_list)})', icon='ARMATURE_DATA')
+
+        # select
+        rows = max(3, min(len(pg.sequence_list), 10))
+
+        row = box.row()
+        col = row.column()
+
+        row2 = col.row(align=True)
+        row2.label(text='Select')
+        row2.operator(PsaImportSequencesFromText.bl_idname, text='', icon='TEXT')
+        row2.operator(PsaImportSequencesSelectAll.bl_idname, text='All', icon='CHECKBOX_HLT')
+        row2.operator(PsaImportSequencesDeselectAll.bl_idname, text='None', icon='CHECKBOX_DEHLT')
+
+        col = col.row()
+        col.template_list('PSA_UL_ImportSequenceList', '', pg, 'sequence_list', pg, 'sequence_list_index', rows=rows)
+
+        col = layout.column(heading='')
+        col.use_property_split = True
+        col.use_property_decorate = False
+        col.prop(pg, 'should_overwrite')
+
+        col = layout.column(heading='Write')
+        col.use_property_split = True
+        col.use_property_decorate = False
+        col.prop(pg, 'should_write_keyframes')
+        col.prop(pg, 'should_write_metadata')
+
+        selected_sequence_count = sum(map(lambda x: x.is_selected, pg.sequence_list))
+
+        row = layout.row()
+
+        import_button_text = 'Import'
+        if selected_sequence_count > 0:
+            import_button_text = f'Import ({selected_sequence_count})'
+
+        row.operator(PsaImportOperator.bl_idname, text=import_button_text)
+
+
+class PsaImportFileReload(Operator):
+    bl_idname = 'psa_import.file_reload'
+    bl_label = 'Refresh'
+    bl_options = {'INTERNAL'}
+    bl_description = 'Refresh the PSA file'
+
+    def execute(self, context):
+        load_psa_file(context)
+        return {"FINISHED"}
+
+
+class PsaImportSelectFile(Operator):
+    bl_idname = 'psa_import.select_file'
+    bl_label = 'Select'
+    bl_options = {'INTERNAL'}
+    bl_description = 'Select a PSA file from which to import animations'
+    filepath: bpy.props.StringProperty(subtype='FILE_PATH')
+    filter_glob: bpy.props.StringProperty(default="*.psa", options={'HIDDEN'})
+
+    def execute(self, context):
+        getattr(context.scene, 'psa_import').psa_file_path = self.filepath
+        return {"FINISHED"}
+
+    def invoke(self, context, event):
+        context.window_manager.fileselect_add(self)
+        return {"RUNNING_MODAL"}
+
+
+class PsaImportOperator(Operator):
+    bl_idname = 'psa_import.import'
+    bl_label = 'Import'
+    bl_description = 'Import the selected animations into the scene as actions'
+    bl_options = {'INTERNAL', 'UNDO'}
+
+    @classmethod
+    def poll(cls, context):
+        pg = getattr(context.scene, 'psa_import')
+        active_object = context.view_layer.objects.active
+        if active_object is None or active_object.type != 'ARMATURE':
+            return False
+        return any(map(lambda x: x.is_selected, pg.sequence_list))
+
+    def execute(self, context):
+        pg = getattr(context.scene, 'psa_import')
+        psa_reader = PsaReader(pg.psa_file_path)
+        sequence_names = [x.action_name for x in pg.sequence_list if x.is_selected]
+
+        options = PsaImportOptions()
+        options.sequence_names = sequence_names
+        options.should_use_fake_user = pg.should_use_fake_user
+        options.should_stash = pg.should_stash
+        options.action_name_prefix = pg.action_name_prefix if pg.should_use_action_name_prefix else ''
+        options.should_overwrite = pg.should_overwrite
+        options.should_write_metadata = pg.should_write_metadata
+        options.should_write_keyframes = pg.should_write_keyframes
+        options.should_convert_to_samples = pg.should_convert_to_samples
+        options.bone_mapping_mode = pg.bone_mapping_mode
+
+        result = import_psa(psa_reader, context.view_layer.objects.active, options)
+
+        if len(result.warnings) > 0:
+            message = f'Imported {len(sequence_names)} action(s) with {len(result.warnings)} warning(s)\n'
+            message += '\n'.join(result.warnings)
+            self.report({'WARNING'}, message)
+        else:
+            self.report({'INFO'}, f'Imported {len(sequence_names)} action(s)')
+
+        return {'FINISHED'}
+
+
+class PsaImportFileSelectOperator(Operator, ImportHelper):
+    bl_idname = 'psa_import.file_select'
+    bl_label = 'File Select'
+    bl_options = {'INTERNAL'}
+    filename_ext = '.psa'
+    filter_glob: StringProperty(default='*.psa', options={'HIDDEN'})
+    filepath: StringProperty(
+        name='File Path',
+        description='File path used for importing the PSA file',
+        maxlen=1024,
+        default='')
+
+    def invoke(self, context, event):
+        context.window_manager.fileselect_add(self)
+        return {'RUNNING_MODAL'}
+
+    def execute(self, context):
+        pg = getattr(context.scene, 'psa_import')
+        pg.psa_file_path = self.filepath
+        return {'FINISHED'}
+
+
+classes = (
+    PsaImportActionListItem,
+    PsaBonePropertyGroup,
+    PsaDataPropertyGroup,
+    PsaImportPropertyGroup,
+    PSA_UL_SequenceList,
+    PSA_UL_ImportSequenceList,
+    PSA_UL_ImportActionList,
+    PsaImportSequencesSelectAll,
+    PsaImportSequencesDeselectAll,
+    PsaImportSequencesFromText,
+    PsaImportFileReload,
+    PSA_PT_ImportPanel,
+    PSA_PT_ImportPanel_Advanced,
+    PsaImportOperator,
+    PsaImportFileSelectOperator,
+    PsaImportSelectFile,
+)

io_scene_psk_psa/psa/reader.py

@@ -0,0 +1,99 @@
+import ctypes
+
+import numpy as np
+
+from .data import *
+
+
+class PsaReader(object):
+    """
+    This class reads the sequences and bone information immediately upon instantiation and holds onto a file handle.
+    The keyframe data is not read into memory upon instantiation due to its potentially very large size.
+    To read the key data for a particular sequence, call :read_sequence_keys.
+    """
+
+    def __init__(self, path):
+        self.keys_data_offset: int = 0
+        self.fp = open(path, 'rb')
+        self.psa: Psa = self._read(self.fp)
+
+    @property
+    def bones(self):
+        return self.psa.bones
+
+    @property
+    def sequences(self):
+        return self.psa.sequences
+
+    def read_sequence_data_matrix(self, sequence_name: str) -> np.ndarray:
+        """
+        Reads and returns the data matrix for the given sequence.
+        @param sequence_name: The name of the sequence.
+        @return: An FxBx7 matrix where F is the number of frames, B is the number of bones.
+        """
+        sequence = self.psa.sequences[sequence_name]
+        keys = self.read_sequence_keys(sequence_name)
+        bone_count = len(self.bones)
+        matrix_size = sequence.frame_count, bone_count, 7
+        matrix = np.zeros(matrix_size)
+        keys_iter = iter(keys)
+        for frame_index in range(sequence.frame_count):
+            for bone_index in range(bone_count):
+                matrix[frame_index, bone_index, :] = list(next(keys_iter).data)
+        return matrix
+
+    def read_sequence_keys(self, sequence_name: str) -> List[Psa.Key]:
+        """
+        Reads and returns the key data for a sequence.
+
+        @param sequence_name: The name of the sequence.
+        @return: A list of Psa.Keys.
+        """
+        # Set the file reader to the beginning of the keys data
+        sequence = self.psa.sequences[sequence_name]
+        data_size = sizeof(Psa.Key)
+        bone_count = len(self.psa.bones)
+        buffer_length = data_size * bone_count * sequence.frame_count
+        sequence_keys_offset = self.keys_data_offset + (sequence.frame_start_index * bone_count * data_size)
+        self.fp.seek(sequence_keys_offset, 0)
+        buffer = self.fp.read(buffer_length)
+        offset = 0
+        keys = []
+        for _ in range(sequence.frame_count * bone_count):
+            key = Psa.Key.from_buffer_copy(buffer, offset)
+            keys.append(key)
+            offset += data_size
+        return keys
+
+    @staticmethod
+    def _read_types(fp, data_class, section: Section, data):
+        buffer_length = section.data_size * section.data_count
+        buffer = fp.read(buffer_length)
+        offset = 0
+        for _ in range(section.data_count):
+            data.append(data_class.from_buffer_copy(buffer, offset))
+            offset += section.data_size
+
+    def _read(self, fp) -> Psa:
+        psa = Psa()
+        while fp.read(1):
+            fp.seek(-1, 1)
+            section = Section.from_buffer_copy(fp.read(ctypes.sizeof(Section)))
+            if section.name == b'ANIMHEAD':
+                pass
+            elif section.name == b'BONENAMES':
+                PsaReader._read_types(fp, Psa.Bone, section, psa.bones)
+            elif section.name == b'ANIMINFO':
+                sequences = []
+                PsaReader._read_types(fp, Psa.Sequence, section, sequences)
+                for sequence in sequences:
+                    psa.sequences[sequence.name.decode()] = sequence
+            elif section.name == b'ANIMKEYS':
+                # Skip keys on this pass. We will keep this file open and read from it as needed.
+                self.keys_data_offset = fp.tell()
+                fp.seek(section.data_size * section.data_count, 1)
+            elif section.name == b'SCALEKEYS':
+                fp.seek(section.data_size * section.data_count, 1)
+            else:
+                raise RuntimeError(f'Unrecognized section "{section.name}"')
+        return psa

io_scene_psk_psa/psk/builder.py

@@ -0,0 +1,272 @@
+import typing
+
+import bmesh
+import bpy
+from bpy.types import Armature
+
+from .data import *
+from ..helpers import *
+
+
+class PskInputObjects(object):
+    def __init__(self):
+        self.mesh_objects = []
+        self.armature_object = None
+
+
+class PskBuildOptions(object):
+    def __init__(self):
+        self.bone_filter_mode = 'ALL'
+        self.bone_group_indices: List[int] = []
+        self.use_raw_mesh_data = True
+        self.material_names: List[str] = []
+        self.should_ignore_bone_name_restrictions = False
+
+
+def get_psk_input_objects(context) -> PskInputObjects:
+    input_objects = PskInputObjects()
+    for selected_object in context.view_layer.objects.selected:
+        if selected_object.type != 'MESH':
+            raise RuntimeError(f'Selected object "{selected_object.name}" is not a mesh')
+
+    input_objects.mesh_objects = context.view_layer.objects.selected
+
+    if len(input_objects.mesh_objects) == 0:
+        raise RuntimeError('At least one mesh must be selected')
+
+    for mesh_object in input_objects.mesh_objects:
+        if len(mesh_object.data.materials) == 0:
+            raise RuntimeError(f'Mesh "{mesh_object.name}" must have at least one material')
+
+    # Ensure that there are either no armature modifiers (static mesh)
+    # or that there is exactly one armature modifier object shared between
+    # all selected meshes
+    armature_modifier_objects = set()
+
+    for mesh_object in input_objects.mesh_objects:
+        modifiers = [x for x in mesh_object.modifiers if x.type == 'ARMATURE']
+        if len(modifiers) == 0:
+            continue
+        elif len(modifiers) > 1:
+            raise RuntimeError(f'Mesh "{mesh_object.name}" must have only one armature modifier')
+        armature_modifier_objects.add(modifiers[0].object)
+
+    if len(armature_modifier_objects) > 1:
+        raise RuntimeError('All selected meshes must have the same armature modifier')
+    elif len(armature_modifier_objects) == 1:
+        input_objects.armature_object = list(armature_modifier_objects)[0]
+
+    return input_objects
+
+
+def build_psk(context, options: PskBuildOptions) -> Psk:
+    input_objects = get_psk_input_objects(context)
+
+    armature_object: bpy.types.Object = input_objects.armature_object
+
+    psk = Psk()
+    bones = []
+
+    if armature_object is None:
+        # If the mesh has no armature object, simply assign it a dummy bone at the root to satisfy the requirement
+        # that a PSK file must have at least one bone.
+        psk_bone = Psk.Bone()
+        psk_bone.name = bytes('root', encoding='windows-1252')
+        psk_bone.flags = 0
+        psk_bone.children_count = 0
+        psk_bone.parent_index = 0
+        psk_bone.location = Vector3.zero()
+        psk_bone.rotation = Quaternion.identity()
+        psk.bones.append(psk_bone)
+    else:
+        bone_names = get_export_bone_names(armature_object, options.bone_filter_mode, options.bone_group_indices)
+        armature_data = typing.cast(Armature, armature_object.data)
+        bones = [armature_data.bones[bone_name] for bone_name in bone_names]
+
+        # Check that all bone names are valid.
+        if not options.should_ignore_bone_name_restrictions:
+            check_bone_names(map(lambda x: x.name, bones))
+
+        for bone in bones:
+            psk_bone = Psk.Bone()
+            psk_bone.name = bytes(bone.name, encoding='windows-1252')
+            psk_bone.flags = 0
+            psk_bone.children_count = 0
+
+            try:
+                parent_index = bones.index(bone.parent)
+                psk_bone.parent_index = parent_index
+                psk.bones[parent_index].children_count += 1
+            except ValueError:
+                psk_bone.parent_index = -1
+
+            if bone.parent is not None:
+                rotation = bone.matrix.to_quaternion().conjugated()
+                inverse_parent_rotation = bone.parent.matrix.to_quaternion().inverted()
+                parent_head = inverse_parent_rotation @ bone.parent.head
+                parent_tail = inverse_parent_rotation @ bone.parent.tail
+                location = (parent_tail - parent_head) + bone.head
+            else:
+                armature_local_matrix = armature_object.matrix_local
+                location = armature_local_matrix @ bone.head
+                bone_rotation = bone.matrix.to_quaternion().conjugated()
+                local_rotation = armature_local_matrix.to_3x3().to_quaternion().conjugated()
+                rotation = bone_rotation @ local_rotation
+                rotation.conjugate()
+
+            psk_bone.location.x = location.x
+            psk_bone.location.y = location.y
+            psk_bone.location.z = location.z
+
+            psk_bone.rotation.w = rotation.w
+            psk_bone.rotation.x = rotation.x
+            psk_bone.rotation.y = rotation.y
+            psk_bone.rotation.z = rotation.z
+
+            psk.bones.append(psk_bone)
+
+    # MATERIALS
+    material_names = options.material_names
+
+    for material_name in material_names:
+        psk_material = Psk.Material()
+        psk_material.name = bytes(material_name, encoding='windows-1252')
+        psk_material.texture_index = len(psk.materials)
+        psk.materials.append(psk_material)
+
+    for input_mesh_object in input_objects.mesh_objects:
+
+        # MATERIALS
+        material_indices = [material_names.index(material.name) for material in input_mesh_object.data.materials]
+
+        # MESH DATA
+        if options.use_raw_mesh_data:
+            mesh_object = input_mesh_object
+            mesh_data = input_mesh_object.data
+        else:
+            # Create a copy of the mesh object after non-armature modifiers are applied.
+
+            # Temporarily force the armature into the rest position.
+            # We will undo this later.
+            old_pose_position = armature_object.data.pose_position
+            armature_object.data.pose_position = 'REST'
+
+            depsgraph = context.evaluated_depsgraph_get()
+            bm = bmesh.new()
+            bm.from_object(input_mesh_object, depsgraph)
+            mesh_data = bpy.data.meshes.new('')
+            bm.to_mesh(mesh_data)
+            del bm
+            mesh_object = bpy.data.objects.new('', mesh_data)
+            mesh_object.matrix_world = input_mesh_object.matrix_world
+
+            # Copy the vertex groups
+            for vertex_group in input_mesh_object.vertex_groups:
+                mesh_object.vertex_groups.new(name=vertex_group.name)
+
+            # Restore the previous pose position on the armature.
+            armature_object.data.pose_position = old_pose_position
+
+        vertex_offset = len(psk.points)
+
+        # VERTICES
+        for vertex in mesh_data.vertices:
+            point = Vector3()
+            v = mesh_object.matrix_world @ vertex.co
+            point.x = v.x
+            point.y = v.y
+            point.z = v.z
+            psk.points.append(point)
+
+        uv_layer = mesh_data.uv_layers.active.data
+
+        # WEDGES
+        mesh_data.calc_loop_triangles()
+
+        # Build a list of non-unique wedges.
+        wedges = []
+        for loop_index, loop in enumerate(mesh_data.loops):
+            wedge = Psk.Wedge()
+            wedge.point_index = loop.vertex_index + vertex_offset
+            wedge.u, wedge.v = uv_layer[loop_index].uv
+            wedge.v = 1.0 - wedge.v
+            wedges.append(wedge)
+
+        # Assign material indices to the wedges.
+        for triangle in mesh_data.loop_triangles:
+            for loop_index in triangle.loops:
+                wedges[loop_index].material_index = material_indices[triangle.material_index]
+
+        # Populate the list of wedges with unique wedges & build a look-up table of loop indices to wedge indices
+        wedge_indices = {}
+        loop_wedge_indices = [-1] * len(mesh_data.loops)
+        for loop_index, wedge in enumerate(wedges):
+            wedge_hash = hash(wedge)
+            if wedge_hash in wedge_indices:
+                loop_wedge_indices[loop_index] = wedge_indices[wedge_hash]
+            else:
+                wedge_index = len(psk.wedges)
+                wedge_indices[wedge_hash] = wedge_index
+                psk.wedges.append(wedge)
+                loop_wedge_indices[loop_index] = wedge_index
+
+        # FACES
+        poly_groups, groups = mesh_data.calc_smooth_groups(use_bitflags=True)
+        for f in mesh_data.loop_triangles:
+            face = Psk.Face()
+            face.material_index = material_indices[f.material_index]
+            face.wedge_indices[0] = loop_wedge_indices[f.loops[2]]
+            face.wedge_indices[1] = loop_wedge_indices[f.loops[1]]
+            face.wedge_indices[2] = loop_wedge_indices[f.loops[0]]
+            face.smoothing_groups = poly_groups[f.polygon_index]
+            psk.faces.append(face)
+
+        # WEIGHTS
+        if armature_object is not None:
+            armature_data = typing.cast(Armature, armature_object.data)
+            # Because the vertex groups may contain entries for which there is no matching bone in the armature,
+            # we must filter them out and not export any weights for these vertex groups.
+            bone_names = [x.name for x in bones]
+            vertex_group_names = [x.name for x in mesh_object.vertex_groups]
+            vertex_group_bone_indices = dict()
+            for vertex_group_index, vertex_group_name in enumerate(vertex_group_names):
+                try:
+                    vertex_group_bone_indices[vertex_group_index] = bone_names.index(vertex_group_name)
+                except ValueError:
+                    # The vertex group does not have a matching bone in the list of bones to be exported.
+                    # Check to see if there is an associated bone for this vertex group that exists in the armature.
+                    # If there is, we can traverse the ancestors of that bone to find an alternate bone to use for
+                    # weighting the vertices belonging to this vertex group.
+                    if vertex_group_name in armature_data.bones:
+                        bone = armature_data.bones[vertex_group_name]
+                        while bone is not None:
+                            try:
+                                bone_index = bone_names.index(bone.name)
+                                vertex_group_bone_indices[vertex_group_index] = bone_index
+                                break
+                            except ValueError:
+                                bone = bone.parent
+            for vertex_group_index, vertex_group in enumerate(mesh_object.vertex_groups):
+                if vertex_group_index not in vertex_group_bone_indices:
+                    # Vertex group has no associated bone, skip it.
+                    continue
+                bone_index = vertex_group_bone_indices[vertex_group_index]
+                for vertex_index in range(len(mesh_data.vertices)):
+                    try:
+                        weight = vertex_group.weight(vertex_index)
+                    except RuntimeError:
+                        continue
+                    if weight == 0.0:
+                        continue
+                    w = Psk.Weight()
+                    w.bone_index = bone_index
+                    w.point_index = vertex_offset + vertex_index
+                    w.weight = weight
+                    psk.weights.append(w)
+
+        if not options.use_raw_mesh_data:
+            bpy.data.objects.remove(mesh_object)
+            bpy.data.meshes.remove(mesh_data)
+            del mesh_data
+
+    return psk

io_scene_psk_psa/psk/data.py

@@ -1,35 +1,52 @@
 from typing import List
+
 from ..data import *
 
 
 class Psk(object):
+    class Wedge(object):
+        def __init__(self):
+            self.point_index: int = 0
+            self.u: float = 0.0
+            self.v: float = 0.0
+            self.material_index: int = 0
+
+        def __hash__(self):
+            return hash(f'{self.point_index}-{self.u}-{self.v}-{self.material_index}')
 
     class Wedge16(Structure):
         _fields_ = [
-            ('point_index', c_int16),
+            ('point_index', c_uint16),
             ('padding1', c_int16),
             ('u', c_float),
             ('v', c_float),
-            ('material_index', c_int8),
+            ('material_index', c_uint8),
             ('reserved', c_int8),
             ('padding2', c_int16)
         ]
 
     class Wedge32(Structure):
         _fields_ = [
-            ('point_index', c_int32),
+            ('point_index', c_uint32),
             ('u', c_float),
             ('v', c_float),
-            ('material_index', c_int32)
+            ('material_index', c_uint32)
         ]
 
     class Face(Structure):
         _fields_ = [
-            ('wedge_index_1', c_int16),
+            ('wedge_indices', c_uint16 * 3),
-            ('wedge_index_2', c_int16),
+            ('material_index', c_uint8),
-            ('wedge_index_3', c_int16),
+            ('aux_material_index', c_uint8),
-            ('material_index', c_int8),
+            ('smoothing_groups', c_int32)
-            ('aux_material_index', c_int8),
+        ]
+
+    class Face32(Structure):
+        _pack_ = 1
+        _fields_ = [
+            ('wedge_indices', c_uint32 * 3),
+            ('material_index', c_uint8),
+            ('aux_material_index', c_uint8),
             ('smoothing_groups', c_int32)
         ]
 
@@ -63,10 +80,25 @@ class Psk(object):
             ('bone_index', c_int32),
         ]
 
+    @property
+    def has_extra_uvs(self):
+        return len(self.extra_uvs) > 0
+
+    @property
+    def has_vertex_colors(self):
+        return len(self.vertex_colors) > 0
+
+    @property
+    def has_vertex_normals(self):
+        return len(self.vertex_normals) > 0
+
     def __init__(self):
         self.points: List[Vector3] = []
-        self.wedges: List[Psk.Wedge16] = []
+        self.wedges: List[Psk.Wedge] = []
         self.faces: List[Psk.Face] = []
         self.materials: List[Psk.Material] = []
         self.weights: List[Psk.Weight] = []
         self.bones: List[Psk.Bone] = []
+        self.extra_uvs: List[Vector2] = []
+        self.vertex_colors: List[Color] = []
+        self.vertex_normals: List[Vector3] = []

io_scene_psk_psa/psk/exporter.py

@@ -0,0 +1,272 @@
+from typing import Type
+
+from bpy.props import BoolProperty, StringProperty, CollectionProperty, IntProperty, EnumProperty
+from bpy.types import Operator, PropertyGroup, UIList
+from bpy_extras.io_utils import ExportHelper
+
+from .builder import build_psk, PskBuildOptions, get_psk_input_objects
+from .data import *
+from ..helpers import populate_bone_group_list
+from ..types import BoneGroupListItem
+
+MAX_WEDGE_COUNT = 65536
+MAX_POINT_COUNT = 4294967296
+MAX_BONE_COUNT = 256
+MAX_MATERIAL_COUNT = 256
+
+
+def _write_section(fp, name: bytes, data_type: Type[Structure] = None, data: list = None):
+    section = Section()
+    section.name = name
+    if data_type is not None and data is not None:
+        section.data_size = sizeof(data_type)
+        section.data_count = len(data)
+    fp.write(section)
+    if data is not None:
+        for datum in data:
+            fp.write(datum)
+
+
+def export_psk(psk: Psk, path: str):
+    if len(psk.wedges) > MAX_WEDGE_COUNT:
+        raise RuntimeError(f'Number of wedges ({len(psk.wedges)}) exceeds limit of {MAX_WEDGE_COUNT}')
+    if len(psk.points) > MAX_POINT_COUNT:
+        raise RuntimeError(f'Numbers of vertices ({len(psk.points)}) exceeds limit of {MAX_POINT_COUNT}')
+    if len(psk.materials) > MAX_MATERIAL_COUNT:
+        raise RuntimeError(f'Number of materials ({len(psk.materials)}) exceeds limit of {MAX_MATERIAL_COUNT}')
+    if len(psk.bones) > MAX_BONE_COUNT:
+        raise RuntimeError(f'Number of bones ({len(psk.bones)}) exceeds limit of {MAX_BONE_COUNT}')
+    elif len(psk.bones) == 0:
+        raise RuntimeError(f'At least one bone must be marked for export')
+
+    with open(path, 'wb') as fp:
+        _write_section(fp, b'ACTRHEAD')
+        _write_section(fp, b'PNTS0000', Vector3, psk.points)
+
+        wedges = []
+        for index, w in enumerate(psk.wedges):
+            wedge = Psk.Wedge16()
+            wedge.material_index = w.material_index
+            wedge.u = w.u
+            wedge.v = w.v
+            wedge.point_index = w.point_index
+            wedges.append(wedge)
+
+        _write_section(fp, b'VTXW0000', Psk.Wedge16, wedges)
+        _write_section(fp, b'FACE0000', Psk.Face, psk.faces)
+        _write_section(fp, b'MATT0000', Psk.Material, psk.materials)
+        _write_section(fp, b'REFSKELT', Psk.Bone, psk.bones)
+        _write_section(fp, b'RAWWEIGHTS', Psk.Weight, psk.weights)
+
+
+def is_bone_filter_mode_item_available(context, identifier):
+    input_objects = get_psk_input_objects(context)
+    armature_object = input_objects.armature_object
+    if identifier == 'BONE_GROUPS':
+        if not armature_object or not armature_object.pose or not armature_object.pose.bone_groups:
+            return False
+    # else if... you can set up other conditions if you add more options
+    return True
+
+
+class PSK_UL_MaterialList(UIList):
+    def draw_item(self, context, layout, data, item, icon, active_data, active_propname, index):
+        row = layout.row()
+        row.label(text=str(getattr(item, 'material_name')), icon='MATERIAL')
+
+
+class MaterialListItem(PropertyGroup):
+    material_name: StringProperty()
+    index: IntProperty()
+
+    @property
+    def name(self):
+        return self.material_name
+
+
+def populate_material_list(mesh_objects, material_list):
+    material_list.clear()
+
+    material_names = []
+    for mesh_object in mesh_objects:
+        for i, material in enumerate(mesh_object.data.materials):
+            # TODO: put this in the poll arg?
+            if material is None:
+                raise RuntimeError('Material cannot be empty (index ' + str(i) + ')')
+            if material.name not in material_names:
+                material_names.append(material.name)
+
+    for index, material_name in enumerate(material_names):
+        m = material_list.add()
+        m.material_name = material_name
+        m.index = index
+
+
+class PskMaterialListItemMoveUp(Operator):
+    bl_idname = 'psk_export.material_list_item_move_up'
+    bl_label = 'Move Up'
+    bl_options = {'INTERNAL'}
+    bl_description = 'Move the selected material up one slot'
+
+    @classmethod
+    def poll(cls, context):
+        pg = getattr(context.scene, 'psk_export')
+        return pg.material_list_index > 0
+
+    def execute(self, context):
+        pg = getattr(context.scene, 'psk_export')
+        pg.material_list.move(pg.material_list_index, pg.material_list_index - 1)
+        pg.material_list_index -= 1
+        return {"FINISHED"}
+
+
+class PskMaterialListItemMoveDown(Operator):
+    bl_idname = 'psk_export.material_list_item_move_down'
+    bl_label = 'Move Down'
+    bl_options = {'INTERNAL'}
+    bl_description = 'Move the selected material down one slot'
+
+    @classmethod
+    def poll(cls, context):
+        pg = getattr(context.scene, 'psk_export')
+        return pg.material_list_index < len(pg.material_list) - 1
+
+    def execute(self, context):
+        pg = getattr(context.scene, 'psk_export')
+        pg.material_list.move(pg.material_list_index, pg.material_list_index + 1)
+        pg.material_list_index += 1
+        return {"FINISHED"}
+
+
+class PskExportOperator(Operator, ExportHelper):
+    bl_idname = 'export.psk'
+    bl_label = 'Export'
+    bl_options = {'INTERNAL', 'UNDO'}
+    __doc__ = 'Export mesh and armature to PSK'
+    filename_ext = '.psk'
+    filter_glob: StringProperty(default='*.psk', options={'HIDDEN'})
+
+    filepath: StringProperty(
+        name='File Path',
+        description='File path used for exporting the PSK file',
+        maxlen=1024,
+        default='')
+
+    def invoke(self, context, event):
+        try:
+            input_objects = get_psk_input_objects(context)
+        except RuntimeError as e:
+            self.report({'ERROR_INVALID_CONTEXT'}, str(e))
+            return {'CANCELLED'}
+
+        pg = getattr(context.scene, 'psk_export')
+
+        # Populate bone groups list.
+        populate_bone_group_list(input_objects.armature_object, pg.bone_group_list)
+
+        try:
+            populate_material_list(input_objects.mesh_objects, pg.material_list)
+        except RuntimeError as e:
+            self.report({'ERROR_INVALID_CONTEXT'}, str(e))
+            return {'CANCELLED'}
+
+        context.window_manager.fileselect_add(self)
+
+        return {'RUNNING_MODAL'}
+
+    @classmethod
+    def poll(cls, context):
+        try:
+            get_psk_input_objects(context)
+        except RuntimeError as e:
+            cls.poll_message_set(str(e))
+            return False
+        return True
+
+    def draw(self, context):
+        layout = self.layout
+        pg = getattr(context.scene, 'psk_export')
+
+        layout.prop(pg, 'use_raw_mesh_data')
+
+        # BONES
+        layout.label(text='Bones', icon='BONE_DATA')
+        bone_filter_mode_items = pg.bl_rna.properties['bone_filter_mode'].enum_items_static
+        row = layout.row(align=True)
+        for item in bone_filter_mode_items:
+            identifier = item.identifier
+            item_layout = row.row(align=True)
+            item_layout.prop_enum(pg, 'bone_filter_mode', item.identifier)
+            item_layout.enabled = is_bone_filter_mode_item_available(context, identifier)
+
+        if pg.bone_filter_mode == 'BONE_GROUPS':
+            row = layout.row()
+            rows = max(3, min(len(pg.bone_group_list), 10))
+            row.template_list('PSX_UL_BoneGroupList', '', pg, 'bone_group_list', pg, 'bone_group_list_index', rows=rows)
+
+        layout.separator()
+
+        # MATERIALS
+        layout.label(text='Materials', icon='MATERIAL')
+        row = layout.row()
+        rows = max(3, min(len(pg.bone_group_list), 10))
+        row.template_list('PSK_UL_MaterialList', '', pg, 'material_list', pg, 'material_list_index', rows=rows)
+        col = row.column(align=True)
+        col.operator(PskMaterialListItemMoveUp.bl_idname, text='', icon='TRIA_UP')
+        col.operator(PskMaterialListItemMoveDown.bl_idname, text='', icon='TRIA_DOWN')
+
+        layout.separator()
+
+        layout.prop(pg, 'should_ignore_bone_name_restrictions')
+
+    def execute(self, context):
+        pg = context.scene.psk_export
+        options = PskBuildOptions()
+        options.bone_filter_mode = pg.bone_filter_mode
+        options.bone_group_indices = [x.index for x in pg.bone_group_list if x.is_selected]
+        options.use_raw_mesh_data = pg.use_raw_mesh_data
+        options.material_names = [m.material_name for m in pg.material_list]
+        options.should_ignore_bone_name_restrictions = pg.should_ignore_bone_name_restrictions
+
+        try:
+            psk = build_psk(context, options)
+            export_psk(psk, self.filepath)
+            self.report({'INFO'}, f'PSK export successful')
+        except RuntimeError as e:
+            self.report({'ERROR_INVALID_CONTEXT'}, str(e))
+            return {'CANCELLED'}
+        return {'FINISHED'}
+
+
+class PskExportPropertyGroup(PropertyGroup):
+    bone_filter_mode: EnumProperty(
+        name='Bone Filter',
+        options=set(),
+        description='',
+        items=(
+            ('ALL', 'All', 'All bones will be exported.'),
+            ('BONE_GROUPS', 'Bone Groups',
+             'Only bones belonging to the selected bone groups and their ancestors will be exported.')
+        )
+    )
+    bone_group_list: CollectionProperty(type=BoneGroupListItem)
+    bone_group_list_index: IntProperty(default=0)
+    use_raw_mesh_data: BoolProperty(default=False, name='Raw Mesh Data', description='No modifiers will be evaluated as part of the exported mesh')
+    material_list: CollectionProperty(type=MaterialListItem)
+    material_list_index: IntProperty(default=0)
+    should_ignore_bone_name_restrictions: BoolProperty(
+        default=False,
+        name='Ignore Bone Name Restrictions',
+        description='Bone names restrictions will be ignored. Note that bone names without properly formatted names '
+                    'cannot be referenced in scripts.'
+    )
+
+
+classes = (
+    MaterialListItem,
+    PSK_UL_MaterialList,
+    PskMaterialListItemMoveUp,
+    PskMaterialListItemMoveDown,
+    PskExportOperator,
+    PskExportPropertyGroup,
+)

io_scene_psk_psa/psk/importer.py

@@ -0,0 +1,367 @@
+import os
+import sys
+from math import inf
+from typing import Optional, List
+
+import bmesh
+import bpy
+import numpy as np
+from bpy.props import BoolProperty, EnumProperty, FloatProperty, StringProperty
+from bpy.types import Operator, PropertyGroup, VertexGroup
+from bpy_extras.io_utils import ImportHelper
+from mathutils import Quaternion, Vector, Matrix
+
+from .data import Psk
+from .reader import read_psk
+from ..helpers import rgb_to_srgb
+
+
+class PskImportOptions(object):
+    def __init__(self):
+        self.name = ''
+        self.should_import_mesh = True
+        self.should_import_vertex_colors = True
+        self.vertex_color_space = 'sRGB'
+        self.should_import_vertex_normals = True
+        self.should_import_extra_uvs = True
+        self.should_import_skeleton = True
+        self.bone_length = 1.0
+
+
+class ImportBone(object):
+    """
+    Intermediate bone type for the purpose of construction.
+    """
+    def __init__(self, index: int, psk_bone: Psk.Bone):
+        self.index: int = index
+        self.psk_bone: Psk.Bone = psk_bone
+        self.parent: Optional[ImportBone] = None
+        self.local_rotation: Quaternion = Quaternion()
+        self.local_translation: Vector = Vector()
+        self.world_rotation_matrix: Matrix = Matrix()
+        self.world_matrix: Matrix = Matrix()
+        self.vertex_group = None
+        self.orig_quat: Quaternion = Quaternion()
+        self.orig_loc: Vector = Vector()
+        self.post_quat: Quaternion = Quaternion()
+
+
+class PskImportResult:
+    def __init__(self):
+        self.warnings: List[str] = []
+
+
+def import_psk(psk: Psk, context, options: PskImportOptions) -> PskImportResult:
+    result = PskImportResult()
+    armature_object = None
+
+    if options.should_import_skeleton:
+        # ARMATURE
+        armature_data = bpy.data.armatures.new(options.name)
+        armature_object = bpy.data.objects.new(options.name, armature_data)
+        armature_object.show_in_front = True
+
+        context.scene.collection.objects.link(armature_object)
+
+        try:
+            bpy.ops.object.mode_set(mode='OBJECT')
+        except:
+            pass
+
+        armature_object.select_set(state=True)
+        bpy.context.view_layer.objects.active = armature_object
+
+        bpy.ops.object.mode_set(mode='EDIT')
+
+        import_bones = []
+
+        for bone_index, psk_bone in enumerate(psk.bones):
+            import_bone = ImportBone(bone_index, psk_bone)
+            psk_bone.parent_index = max(0, psk_bone.parent_index)
+            import_bone.local_rotation = Quaternion(tuple(psk_bone.rotation))
+            import_bone.local_translation = Vector(tuple(psk_bone.location))
+            if psk_bone.parent_index == 0 and bone_index == 0:
+                import_bone.world_rotation_matrix = import_bone.local_rotation.to_matrix()
+                import_bone.world_matrix = Matrix.Translation(import_bone.local_translation)
+            import_bones.append(import_bone)
+
+        for bone_index, bone in enumerate(import_bones):
+            if bone.psk_bone.parent_index == 0 and bone_index == 0:
+                continue
+            parent = import_bones[bone.psk_bone.parent_index]
+            bone.parent = parent
+            bone.world_matrix = parent.world_rotation_matrix.to_4x4()
+            translation = bone.local_translation.copy()
+            translation.rotate(parent.world_rotation_matrix)
+            bone.world_matrix.translation = parent.world_matrix.translation + translation
+            bone.world_rotation_matrix = bone.local_rotation.conjugated().to_matrix()
+            bone.world_rotation_matrix.rotate(parent.world_rotation_matrix)
+
+        for import_bone in import_bones:
+            bone_name = import_bone.psk_bone.name.decode('utf-8')
+            edit_bone = armature_data.edit_bones.new(bone_name)
+
+            if import_bone.parent is not None:
+                edit_bone.parent = armature_data.edit_bones[import_bone.psk_bone.parent_index]
+            else:
+                import_bone.local_rotation.conjugate()
+
+            edit_bone.tail = Vector((0.0, options.bone_length, 0.0))
+            edit_bone_matrix = import_bone.local_rotation.conjugated()
+            edit_bone_matrix.rotate(import_bone.world_matrix)
+            edit_bone_matrix = edit_bone_matrix.to_matrix().to_4x4()
+            edit_bone_matrix.translation = import_bone.world_matrix.translation
+            edit_bone.matrix = edit_bone_matrix
+
+            # Store bind pose information in the bone's custom properties.
+            # This information is used when importing animations from PSA files.
+            edit_bone['orig_quat'] = import_bone.local_rotation
+            edit_bone['orig_loc'] = import_bone.local_translation
+            edit_bone['post_quat'] = import_bone.local_rotation.conjugated()
+
+    # MESH
+    if options.should_import_mesh:
+        mesh_data = bpy.data.meshes.new(options.name)
+        mesh_object = bpy.data.objects.new(options.name, mesh_data)
+
+        # MATERIALS
+        for material in psk.materials:
+            # TODO: re-use of materials should be an option
+            bpy_material = bpy.data.materials.new(material.name.decode('utf-8'))
+            mesh_data.materials.append(bpy_material)
+
+        bm = bmesh.new()
+
+        # VERTICES
+        for point in psk.points:
+            bm.verts.new(tuple(point))
+
+        bm.verts.ensure_lookup_table()
+
+        degenerate_face_indices = set()
+        for face_index, face in enumerate(psk.faces):
+            point_indices = [bm.verts[psk.wedges[i].point_index] for i in reversed(face.wedge_indices)]
+            try:
+                bm_face = bm.faces.new(point_indices)
+                bm_face.material_index = face.material_index
+            except ValueError:
+                degenerate_face_indices.add(face_index)
+
+        if len(degenerate_face_indices) > 0:
+            result.warnings.append(f'Discarded {len(degenerate_face_indices)} degenerate face(s).')
+
+        bm.to_mesh(mesh_data)
+
+        # TEXTURE COORDINATES
+        data_index = 0
+        uv_layer = mesh_data.uv_layers.new(name='VTXW0000')
+        for face_index, face in enumerate(psk.faces):
+            if face_index in degenerate_face_indices:
+                continue
+            face_wedges = [psk.wedges[i] for i in reversed(face.wedge_indices)]
+            for wedge in face_wedges:
+                uv_layer.data[data_index].uv = wedge.u, 1.0 - wedge.v
+                data_index += 1
+
+        # EXTRA UVS
+        if psk.has_extra_uvs and options.should_import_extra_uvs:
+            extra_uv_channel_count = int(len(psk.extra_uvs) / len(psk.wedges))
+            wedge_index_offset = 0
+            for extra_uv_index in range(extra_uv_channel_count):
+                data_index = 0
+                uv_layer = mesh_data.uv_layers.new(name=f'EXTRAUV{extra_uv_index}')
+                for face_index, face in enumerate(psk.faces):
+                    if face_index in degenerate_face_indices:
+                        continue
+                    for wedge_index in reversed(face.wedge_indices):
+                        u, v = psk.extra_uvs[wedge_index_offset + wedge_index]
+                        uv_layer.data[data_index].uv = u, 1.0 - v
+                        data_index += 1
+                wedge_index_offset += len(psk.wedges)
+
+        # VERTEX COLORS
+        if psk.has_vertex_colors and options.should_import_vertex_colors:
+            size = (len(psk.points), 4)
+            vertex_colors = np.full(size, inf)
+            vertex_color_data = mesh_data.vertex_colors.new(name='VERTEXCOLOR')
+            ambiguous_vertex_color_point_indices = []
+
+            for wedge_index, wedge in enumerate(psk.wedges):
+                point_index = wedge.point_index
+                psk_vertex_color = psk.vertex_colors[wedge_index].normalized()
+                if vertex_colors[point_index, 0] != inf and tuple(vertex_colors[point_index]) != psk_vertex_color:
+                    ambiguous_vertex_color_point_indices.append(point_index)
+                else:
+                    vertex_colors[point_index] = psk_vertex_color
+
+            if options.vertex_color_space == 'SRGBA':
+                for i in range(vertex_colors.shape[0]):
+                    vertex_colors[i, :3] = tuple(map(lambda x: rgb_to_srgb(x), vertex_colors[i, :3]))
+
+            for loop_index, loop in enumerate(mesh_data.loops):
+                vertex_color = vertex_colors[loop.vertex_index]
+                if vertex_color is not None:
+                    vertex_color_data.data[loop_index].color = vertex_color
+                else:
+                    vertex_color_data.data[loop_index].color = 1.0, 1.0, 1.0, 1.0
+
+            if len(ambiguous_vertex_color_point_indices) > 0:
+                result.warnings.append(
+                    f'{len(ambiguous_vertex_color_point_indices)} vertex(es) with ambiguous vertex colors.')
+
+        # VERTEX NORMALS
+        if psk.has_vertex_normals and options.should_import_vertex_normals:
+            mesh_data.polygons.foreach_set("use_smooth", [True] * len(mesh_data.polygons))
+            normals = []
+            for vertex_normal in psk.vertex_normals:
+                normals.append(tuple(vertex_normal))
+            mesh_data.normals_split_custom_set_from_vertices(normals)
+            mesh_data.use_auto_smooth = True
+
+        bm.normal_update()
+        bm.free()
+
+        # Get a list of all bones that have weights associated with them.
+        vertex_group_bone_indices = set(map(lambda weight: weight.bone_index, psk.weights))
+        vertex_groups: List[Optional[VertexGroup]] = [None] * len(psk.bones)
+        for bone_index, psk_bone in map(lambda x: (x, psk.bones[x]), vertex_group_bone_indices):
+            vertex_groups[bone_index] = mesh_object.vertex_groups.new(name=psk_bone.name.decode('windows-1252'))
+
+        for weight in psk.weights:
+            vertex_groups[weight.bone_index].add((weight.point_index,), weight.weight, 'ADD')
+
+        context.scene.collection.objects.link(mesh_object)
+
+        # Add armature modifier to our mesh object.
+        if options.should_import_skeleton:
+            armature_modifier = mesh_object.modifiers.new(name='Armature', type='ARMATURE')
+            armature_modifier.object = armature_object
+            mesh_object.parent = armature_object
+
+    try:
+        bpy.ops.object.mode_set(mode='OBJECT')
+    except:
+        pass
+
+    return result
+
+
+empty_set = set()
+
+
+class PskImportPropertyGroup(PropertyGroup):
+    should_import_vertex_colors: BoolProperty(
+        default=True,
+        options=empty_set,
+        name='Vertex Colors',
+        description='Import vertex colors from PSKX files, if available'
+    )
+    vertex_color_space: EnumProperty(
+        name='Vertex Color Space',
+        options=empty_set,
+        description='The source vertex color space',
+        default='SRGBA',
+        items=(
+            ('LINEAR', 'Linear', ''),
+            ('SRGBA', 'sRGBA', ''),
+        )
+    )
+    should_import_vertex_normals: BoolProperty(
+        default=True,
+        name='Vertex Normals',
+        options=empty_set,
+        description='Import vertex normals from PSKX files, if available'
+    )
+    should_import_extra_uvs: BoolProperty(
+        default=True,
+        name='Extra UVs',
+        options=empty_set,
+        description='Import extra UV maps from PSKX files, if available'
+    )
+    should_import_mesh: BoolProperty(
+        default=True,
+        name='Import Mesh',
+        options=empty_set,
+        description='Import mesh'
+    )
+    should_import_skeleton: BoolProperty(
+        default=True,
+        name='Import Skeleton',
+        options=empty_set,
+        description='Import skeleton'
+    )
+    bone_length: FloatProperty(
+        default=1.0,
+        min=sys.float_info.epsilon,
+        step=100,
+        soft_min=1.0,
+        name='Bone Length',
+        options=empty_set,
+        description='Length of the bones'
+    )
+
+
+class PskImportOperator(Operator, ImportHelper):
+    bl_idname = 'import.psk'
+    bl_label = 'Import'
+    bl_options = {'INTERNAL', 'UNDO'}
+    __doc__ = 'Load a PSK file'
+    filename_ext = '.psk'
+    filter_glob: StringProperty(default='*.psk;*.pskx', options={'HIDDEN'})
+    filepath: StringProperty(
+        name='File Path',
+        description='File path used for exporting the PSK file',
+        maxlen=1024,
+        default='')
+
+    def execute(self, context):
+        pg = getattr(context.scene, 'psk_import')
+
+        psk = read_psk(self.filepath)
+
+        options = PskImportOptions()
+        options.name = os.path.splitext(os.path.basename(self.filepath))[0]
+        options.should_import_mesh = pg.should_import_mesh
+        options.should_import_extra_uvs = pg.should_import_extra_uvs
+        options.should_import_vertex_colors = pg.should_import_vertex_colors
+        options.should_import_vertex_normals = pg.should_import_vertex_normals
+        options.vertex_color_space = pg.vertex_color_space
+        options.should_import_skeleton = pg.should_import_skeleton
+        options.bone_length = pg.bone_length
+
+        result = import_psk(psk, context, options)
+
+        if len(result.warnings):
+            message = f'PSK imported with {len(result.warnings)} warning(s)\n'
+            message += '\n'.join(result.warnings)
+            self.report({'WARNING'}, message)
+        else:
+            self.report({'INFO'}, f'PSK imported')
+
+        return {'FINISHED'}
+
+    def draw(self, context):
+        pg = getattr(context.scene, 'psk_import')
+        layout = self.layout
+        layout.prop(pg, 'should_import_mesh')
+        row = layout.column()
+        row.use_property_split = True
+        row.use_property_decorate = False
+        if pg.should_import_mesh:
+            row.prop(pg, 'should_import_vertex_normals')
+            row.prop(pg, 'should_import_extra_uvs')
+            row.prop(pg, 'should_import_vertex_colors')
+            if pg.should_import_vertex_colors:
+                row.prop(pg, 'vertex_color_space')
+        layout.prop(pg, 'should_import_skeleton')
+        row = layout.column()
+        row.use_property_split = True
+        row.use_property_decorate = False
+        if pg.should_import_skeleton:
+            row.prop(pg, 'bone_length')
+
+
+classes = (
+    PskImportOperator,
+    PskImportPropertyGroup,
+)

io_scene_psk_psa/psk/reader.py

@@ -0,0 +1,53 @@
+import ctypes
+import os
+
+from .data import *
+
+
+def _read_types(fp, data_class, section: Section, data):
+    buffer_length = section.data_size * section.data_count
+    buffer = fp.read(buffer_length)
+    offset = 0
+    for _ in range(section.data_count):
+        data.append(data_class.from_buffer_copy(buffer, offset))
+        offset += section.data_size
+
+
+def read_psk(path: str) -> Psk:
+    psk = Psk()
+    with open(path, 'rb') as fp:
+        while fp.read(1):
+            fp.seek(-1, 1)
+            section = Section.from_buffer_copy(fp.read(ctypes.sizeof(Section)))
+            if section.name == b'ACTRHEAD':
+                pass
+            elif section.name == b'PNTS0000':
+                _read_types(fp, Vector3, section, psk.points)
+            elif section.name == b'VTXW0000':
+                if section.data_size == ctypes.sizeof(Psk.Wedge16):
+                    _read_types(fp, Psk.Wedge16, section, psk.wedges)
+                elif section.data_size == ctypes.sizeof(Psk.Wedge32):
+                    _read_types(fp, Psk.Wedge32, section, psk.wedges)
+                else:
+                    raise RuntimeError('Unrecognized wedge format')
+            elif section.name == b'FACE0000':
+                _read_types(fp, Psk.Face, section, psk.faces)
+            elif section.name == b'MATT0000':
+                _read_types(fp, Psk.Material, section, psk.materials)
+            elif section.name == b'REFSKELT':
+                _read_types(fp, Psk.Bone, section, psk.bones)
+            elif section.name == b'RAWWEIGHTS':
+                _read_types(fp, Psk.Weight, section, psk.weights)
+            elif section.name == b'FACE3200':
+                _read_types(fp, Psk.Face32, section, psk.faces)
+            elif section.name == b'VERTEXCOLOR':
+                _read_types(fp, Color, section, psk.vertex_colors)
+            elif section.name.startswith(b'EXTRAUVS'):
+                _read_types(fp, Vector2, section, psk.extra_uvs)
+            elif section.name == b'VTXNORMS':
+                _read_types(fp, Vector3, section, psk.vertex_normals)
+            else:
+                # Section is not handled, skip it.
+                fp.seek(section.data_size * section.data_count, os.SEEK_CUR)
+                print(f'Unrecognized section "{section.name} at position {fp.tell():15}"')
+    return psk

io_scene_psk_psa/types.py

@@ -0,0 +1,24 @@
+from bpy.props import StringProperty, IntProperty, BoolProperty
+from bpy.types import PropertyGroup, UIList, UILayout, Context, AnyType
+
+
+class PSX_UL_BoneGroupList(UIList):
+
+    def draw_item(self, context: Context, layout: UILayout, data: AnyType, item: AnyType, icon: int,
+                  active_data: AnyType, active_property: str, index: int = 0, flt_flag: int = 0):
+        row = layout.row()
+        row.prop(item, 'is_selected', text=getattr(item, 'name'))
+        row.label(text=str(getattr(item, 'count')), icon='BONE_DATA')
+
+
+class BoneGroupListItem(PropertyGroup):
+    name: StringProperty()
+    index: IntProperty()
+    count: IntProperty()
+    is_selected: BoolProperty(default=False)
+
+
+classes = (
+    BoneGroupListItem,
+    PSX_UL_BoneGroupList,
+)