Home

Preface

DISCLAIMER: This tool is not to be used for commercial purposes, nor for redistributing or exposing the original game’s protected assets in any form that violates intellectual property laws.

Ensure any content created using this tool complies with applicable copyright laws in your region.

Properly credit the original creators for any derivative work. This tool and its creator assume no responsibility for misuse or infringement.

• What sssekai_blender_io is

  • A hobby project of mine to study CG, Blender, and reverse engineering.
  • A probably good enough starting point for developing Blender importer plugins for other Unity games.
  • A Blender plugin specialized in importing the game Project SEKAI's (JP: プロジェクトセカイ カラフルステージ！ feat.初音ミク) game assets
    • That allows some interoperability with other asset IO plugins (e.g. mmd_tools)
    • With limited compatibility with other Unity engine games as is

• What sssekai_blender_io isn't

  • A drop-in replacement for other Unity engine asset ripping/recovery tools (e.g. AssetStudio, AssetRipper)
    • Only Meshes (Skinned or static, w/wo Blend Shape), Textures, and Animations are generally supported. See below for Sekai-specific additions.
    • AssetBundles are assumed to be vanilla (no encryption/obfuscation). Headers can be stripped, however.
      • See here for implementing your own decryption scheme for your favorite game
  • A ground-truth reimplementation of the game's rendering pipeline in Blender

Installation

Pleases refer to the main README for instructions

Debugging & Submitting Issues

Please attach the console log of your Blender instance (Window > Show System Console) when submitting a new issue.

The Interface

This paragraph provides extended explanations for operators/properties of the plugin panel (N Key > SSSekai) that would otherwise not be provided elsewhere.

---

NOTE: You can hover your mouse cursor over the fields (in the plugin panel) for tooltips that further explain the functionalities of every operator/property. Their explanations shall be omitted here for the sake of simplicity.

---

Import (Panel)

Unity Version

This allows you to set the unity version sssekai should parse to properly parse the asset bundles. Sssekai's preset unity version is 2022.3.21f1

Please refer to https://github.com/mos9527/sssekai/wiki#note-on-unity-version for more information.

Asset Selector

Directory

Loads the assets of the chosen directory into memory. Depending on the assets' number/size, this may take up a lot of memory

Please take extra care and load directories that only contain the files you're interested in (e.g. by copying selected bundles outside its resident directory and loading them there) so OOMs won't occur.

The assets are selected by the heuristic that these usually are at the root of the Unity Scene, which worked well for Sekai assets. Feel free to modify this section to fit your own case in https://github.com/mos9527/sssekai_blender_io/blob/master/blender/asset.py#L11

Import Type

Specify which type of asset you are working with, Hierarchy or Animation. Make sure to specify which type you are planning on importing, or you will run into issues.

Hierarchy is all of your 3d assets and lighting; stage, character, effects, lights, etc.

Animation is all of the animation files for those 3d and lighting assets.

Search

Search is currently not implemented.

You can search for assets (by their names) with this operator. Assets with the same names are separated.

Material Options

Use Principled BSDF

The imported materials will use the Principled BSDF/PBR node, with the diffuse/base color being Unity's MainTex, which is usually the diffuse color.

This is useful when you want to just export the imported mesh/armature, etc. for use with other DCC tools/game engines/renderers.

Add Outline To Selected

Adds shell outline to the selected mesh(es) by extruding the vertices (optionally, by the amount specified by their vertex colors (as it is in Sekai)) and flipping their normals w/ back-face culling turned on for the outline material, with a Geometry Node SekaiShellOutline.

The strength, scale, etc can be modified in the applied meshes' Modifiers tab, in SekaiShellOutline

Armature Options

Armature as Articulations

Treat skinned meshes as static meshes, ignoring the skinning, etc, so that only the bone structure (if any) will be imported.

This is usually not needed. Might be helpful if you're debugging imported animations since animations can be imported into articulations as well.

Import Physics

Imports Sekai specific physics data into the imported armature by constructing the requisite rigid bodies & constraints. Please note that the imported armature must not be ((merged)) with another face armature beforehand or afterward. Use the attach operator in the Attach Neck panel instead.

Animation Options

• Camera animations may be off-sync. You can set Offset to -100 or similar values, and adjust Camera Offset's Z value (the last one) to some value (that's usually negative) so that the viewport captures your character. (Also remember to change the default character size to fit the camera view as well)

  • This is needed since the game does the same with hardcoded height offset values.

• Concatenating multiple animation clips

  • In most cases, you should Use NLA Clip for this purpose.
  • If merging animation frames into a single, big blob is really desired, set Offset to the end frame number of the previous animation, and toggle on Append, then Import

Import Selected

Imports the selected asset.

• For armatures/articulations, this will import their data and add them to your Scene.

• For animations, you must select an animation target object to begin with.

  • The armatures, and articulations mentioned below must be imported by the plugin itself, or have the Recalculate Hash Table operator applied beforehand.
    • You can only import armature animations (humanoid characters, stage props, etc) into armatures, or articulations.
    • You can only import shape key animations into face/... armatures, or any armature that contains a mesh with shape keys.
  • You can only import camera animations into a existing Blender Camera.

RLA Import (Panel)

This panel is dedicated to importing streaming_live/archive assets, which stores animation/live events/etc in RLA format.

The panel also accepts ZIP archives - see https://github.com/mos9527/sssekai/wiki#streaming-live-rla-segments for more information.

Operation-wise - this part is pretty much the same as the standard asset import. Again, this shall be omitted here for simplicity.

Sekai Character

You need to adjust the heights of the imported characters otherwise they'd be out of view if you'd use a camera animation. To fix this, first select the body armature, and press Make/Update Root Height Scale. Next, find the height value of the character in question using the table below, and paste or type it into the Character Height (in meters) box.

Character	Height (meters)
Ichika	1.61
Saki	1.59
Honami	1.66
Shiho	1.59
Minori	1.58
Haruka	1.63
Airi	1.56
Shizuku	1.68
Kohane	1.56
An	1.60
Akito	1.74
Touya	1.78
Tsukasa	1.72
Emu	1.52
Nene	1.56
Rui	1.80
Kanade	1.54
Mafuyu	1.62
Ena	1.58
Mizuki	1.63
Miku	1.58
Rin	1.52
Len	1.56
Luka	1.62
Meiko	1.67
Kaito	1.75

Neck Attach (Panel)

After selecting your face/.. and body/.. armatures from both individual boxes under Select Targets, you can perform one of the following operations:

• Attach: Attaches the two armatures and models, using bone constraints. Specifically, the face armature will copy the transformations of the Head, Neck bones of the body armature. This is useful if you don't need to export the armature, or you want to use the physics in Blender.
• Merge: Combines the two armatures into one. The bone hierarchy, and the mesh data of the Face mesh, will be changed as a result. This is useful if you want to export the imported mesh,

Misc (Panel)

Recalculate Hash Table

This step is a must if you have changed the bone/object hierarchy and expect the animations to be imported afterward. Or, if you have a newly created/imported elsewhere armature/articulation, this is needed as well.

Since, TL;DR: Exported Unity animations paths are converted to their CRC hashes. This cannot be reversed realistically w/o knowing the full paths beforehand. Hence the requirement to calculate the tables as a pre-processing step.