VS Blender Shape Importer

Pre ALPHA!
Here be dragons.

Vintage Story -> Blender | Shape Importer (Skeletal) bridges the gap between Vintage Story's engine and Blender. Whether you are creating custom blocks, animating entities, or designing new Seraph wearables, this add-on translates .json shape files into standard Blender skeletal meshes.

Currently there are no export options from Blender. This is only for importing (for now).

✨ Feature Overview

• Complete Shape Translation: Accurately(?) imports JSON data, converting it into a standard skeletal mesh in Blender, complete with accurate UV maps and materials.

• Full Animation Support: Automatically converts Vintage Story keyframes, bone offsets, and rotations into native Blender Actions and NLA tracks.

• Seamless Wearable Integration: Import wearables (like clothing or armor) directly onto an existing rig, such as the base Seraph character. The add-on automatically handles bone parenting and structure.

• Smart Texture Auto-Detection: The importer automatically searches your directory tree to find the Vintage Story assets folder to locate and apply textures. Unless you define a custom path.

  ⚠️ Limitations & Known Behaviors

  • Unmapped Textures: The importer relies entirely on the data provided within the shape .json file. If a texture is not explicitly defined in the file's "textures" dictionary (for example, if it is dynamically assigned in the item/block type JSON instead), the add-on cannot resolve it and will generate a placeholder material (e.g., VS_MissingTexture).

  • Import-Only Functionality: This add-on is designed strictly for importing. To export your modified meshes and animations back into Vintage Story's .json format, you will need to use a separate export script or tool. (I am unsure if I can create such an addon for Blender at the moment)

  • Wearable Base Requirement: Importing a wearable (like armor or clothing) strictly requires you to have a base armature (like the Seraph rig) already imported and selected in Object Mode.

  • Base Rig Coordinate Data: For wearable bone offsets to calculate correctly, the target base rig must have been imported using this add-on, as the script reads specific custom properties (like vs_abs_from) generated during the initial base rig import.

  • UV Rotations: The importer handles standard UV rotations (0, 90, 180, and 270 degrees) as defined by the Vintage Story engine. Arbitrary, non-standard UV rotations are not supported.

  • Non-Standard Folder Structures: The automatic texture path detection works by looking for an assets folder in the directory tree. If you are working out of a highly customized or non-standard directory structure without an assets parent folder, you will still need to manually define the texture directory.

---

Installation Instructions

1. Download the VSBL_Shape_Importer.zip file (do not extract it).

2. Open Blender and navigate to Edit > Preferences.

3. Select the Add-ons tab on the left side.

4. Click the Install... button at the top right.

5. Locate and select the downloaded VSBL_Shape_Importer.zip file, then click Install Add-on.

(You can now access the importer via File > Import > Vintage Story Shape (.json)