blender-vintagestory-json

KO | EN

gitlite — search

#claude-code #ai #mcp #typescript #rust #python #cli #ai-agents #claude #security #developer-tools #ai-agent

blender-vintagestory-json

★ 32 Open GitHub ↗

Blender Vintage Story .json model importer/exporter

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

Vintage Story JSON Import/Export
=======================================
Import/export cuboid geometry between Blender and Vintage Story .json model
format. The Blender model must follow very specific restrictions for the
exporter to work (read **Export Guide** below).

Supports import/export uvs. This addon can export solid material colors
packed into an auto-generated image texture (alongside normal textures),
so you can mix textures and solid face colors on Blender meshes.

Tested on Blender 4.5 LTS.

Installation
---------------------------------------
1. `git clone` or download code copy from this repository into your
   Blender's `scripts/addons` folder or custom scripts folder.
2. Enable in **Edit > Preferences > Add-ons**
   (search for *Vintage Story JSON Import/Export*).
3. Restarting Blender may be necessary.

Optional: For relaxed json import (json5), you must have pyjson5 installed. 
Make sure you have pip installed (see https://pip.pypa.io/en/stable/installation/ ), 
then run `pip3 install pyjson5`.

Export Guide/Notes
---------------------------------------
- **Only exports cuboid objects** e.g. Object meshes must be rectangular
  prisms (8 vertices and 6 faces). The local mesh coordinates must be
  aligned to global XYZ axis. **Do not rotate the mesh vertices in edit mode.**
- **All cuboids must be separate objects.**
- **Attach points**: Create an "Empty" type object (e.g.
  **Shift + A > Empty > Arrows**) and name it "attach_{name}", the {name}
  will become an attachpoint. e.g. "attach_Center" will generate an
  attachpoint called "Center". Parent it to associated object: select empty,
  select object parent, then set parent with `Ctrl P > Object`.
- **Animation setup**: Animations must use an armature + bones. Create an
  armature and bones, then parent objects to armature with setting "Bone":
    1. Select armature, enter edit mode (Tab), then select the bone to be
       the parent. Exit back into object mode (Tab).
    2. Select objects that you want to be the children.
    3. Then select the armature, parent using `Ctrl P > Bone`. In the right
       side `Object Properties > Relations` panel the `Parent` should be
       the armature object, the `Parent Type` should be "Bone" and the
       `Parent Bone` should be the bone you previously selected.
    4. Create animation action on the armature, and make keyframes using
       the bones (standard Blender bone animation).
    5. On export, if an object has the same name as its parent bone, it
       will be the object that acts as the bone, the "bone object".
       Otherwise, a random child will be chosen. The other children of
       the bone will be parented to the "bone object" in the exported .json.
- **Animation metadata**: Animation metadata is set in action's N-panel:
  In the `Dope Sheet` > `Action Editor` ui, create or select an action,
  press `N` to view the panel on the right side of the window. There will
  be a tab labelled "VintageStory" which contains animation utils and
  dropdown selection for animation end and activity stopped metadata.
- **Generating solid color textures:** By default, the exporter will
  generate a texture containing all solid material colors. So you can
  texture using just materials + colors without UV mapping or a texture
  image. This works alongside using texture images and uv mapping.
- **Recalculate normals if textures are on wrong faces.** Applying negative
  scales can sometimes flip face normals inside, which causes incorrect
  auto-generated texture colors. Recalculate normals on all meshes to fix
  (`Select All` > `Edit Mode` > `Select All` > `ctrl + shift + N` to
  recalculate and **uncheck inside**).
- **Parenting objects:** You can mix directly parenting object to object
  (`Ctrl P > Object`) along with armature bones. 
- **Special dummy objects:** Create an "Empty" type object (e.g.
  **Shift + A > Empty > Arrows**) and name it "dummy_{name}", the {name}
  will become a dummy element with zero size and all faces disabled. Parent
  it to an associated object: select empty, select object parent, then set
  parent with `Ctrl P > Object`.

Import Guide/Notes
---------------------------------------
- In VS Model Creator, animations are individual object keyframes. This
  does not map well to Blender actions. A Blender action can transform
  multiple bones but only transform a single object directly.
  So instead imported animations are mapped to bone animations.
  The full import is:
    1. Import and build mesh object hierarchy
    2. Traverse mesh hierarchy and set create a bone for each mesh object.
       Move object transform to the bone (sets mesh object transform to
       identity). Armature hierarchy replaces object hierarchy.
    3. Apply the bone transforms as the rest pose. This applies bone
       transforms, sets them to identity, and returns transform to the
       mesh objects.
    4. Animations format is relative displacement from bone rest pose.
       Note that Blender and VintageStory location is applied differently
       (this import/export will handle the conversion between these formats):
        - VintageStory: v' = R\*T\*v (translate first, then rotate)
        - Blender: v' = T\*R\*v (rotate first, then translate)

Export Options
---------------------------------------
|  Option  |  Default   | Description  |
|----------|------------|------------- |
| Selection Only | False | If True, export only selected objects |
| Skip Disabled Render | True | If True, skip objects with render disabled (camera icon in objects list) |
| Use Step Parent | True | If True, transform objects relative to step parents (e.g. for clothing) |
| Translate Origin | True | Fixed translation of coordinates by `(x,y,z)` (in Blender coordinates) |
| Translate X | 8.0 | `x` export recenter coordinate |
| Translate Y | 8.0 | `y` export recenter coordinate |
| Translate Z | 0.0 | `z` export recenter coordinate |
| Texture Subfolder  |  | Subfolder for model in textures folder: `/textures/[subfolder]` |
| Color Texture Name |  | Name of color texture generated `[name].png` (blank defaults to output `.json` filename) |
| Export UVs | True | Exports face UVs |
| Generate Color Texture | False | Auto-textures solid material colors and generates a `.png` image texture exported alongside model (overwrites UVs). By default will get colors from all materials in the Blender file. |
| Only Use Exported Object Colors | False | When exporting auto-generated color texture, only use material colors on exported objects (instead of all materials in file). |
| Texture Size X Override | 0 | Override texture size x in UV export. Sometimes model UV texture size needs to be different than image size (e.g. composing texture skins for seraph). 0 to ignore.
| Texture Size Y Override | 0 | Override texture size y in UV export. Sometimes model UV texture size needs to be different than image size (e.g. composing texture skins for seraph). 0 to ignore.
| Skip Texture Export | False | If true, skip texture and texture size exports (for models using in-game generated textures) |
| Minify .json | False | Enable options to reduce .json file size |
| Decimal Precision | 8 | Number of digits after decimal point in output .json (-1 to disable) |
| Export Armature | True | Export objects using armature hierarchy, auto generates bone elements |
| Export Animations | True | Export animations |
| Generate Animations File | False | Generate separate `model_animations.json` file containing animations |
| Use Main Object as Bone | True | Merges bone and object if they share same name and transform (for vanilla model compatibility) |
| Rotate Shortest Distance | False | Makes animations rotate shortest dist, similar to quarternion slerp |
| Use Animation Version 0 | False | Use default VintageStory animation format incompatible with Blender | 
| Run Post Export Script | False | If True, automatically runs a python script after export (see details below) |
| Post Export Script |  | Name of post export script, e.g. `postprocess.py` |

Import Options
---------------------------------------
|  Option  |  Default   | Description  |
|----------|------------|------------- |
| Import UVs | True | Import face UVs |
| Recenter to Origin | False | Re-centers model center on Blender world origin (overrides translate option) |
| Translate Origin | False | Fixed translation of coordinates by `(x,y,z)` (in Blender coordinates) |
| Translate X | -8.0 | `x` import recenter coordinate |
| Translate Y | -8.0 | `y` import recenter coordinate |
| Translate Z | 0.0 | `z` import recenter coordinate |
| Import Animations | True | Import animations, converts object hierachy to bone hierarchy |

Post Export Python Script
---------------------------------------
By enabling `Run Post Export Script`, this plugin will call the python script
after running export and pass in the full filepath of the exported json file
as the first argument.
- The python file must be located in same folder as where the json file
  is exported into.
- `Post Export Script` setting should just be python filename with
  extension, e.g. `postprocess.py`
- Blender will call the python script as `postprocess.py full/path/to/export.json`
- Python script console output will appear in Blender console
  (Window > Toggle System Console)

This post export script can be used for custom post-processing, such as
modifying elements (to add properties not supported by the Blender plugin)
and/or to automatically copy a post-processed file into your final
destination folder.

Below is a sample template of a script that reads in the exported json model
for post-processing:
```python
import json
import argparse

### parse first arg as full filepath of exported json file
parser = argparse.ArgumentParser()
parser.add_argument(
    "path_exported_json",
    help="full filepath of exported .json file",
)
args = parser.parse_args()

with open(args.path_exported_json, "r") as f:
    model = json.load(f)

### do post-processing of model

### and/or automatically write to final destination
# with open(path_out_json, "w+") as f:
#     json.dump(model, f, indent=2)
```

Additional Utils
---------------------------------------
This will also add a utils panel in the "N Panel" named "VintageStory"
(accessed by pressing "N" with default hotkeys). This panel contains
VintageStory-specific utility operators for UVs, texturing, and 
animations.

### Model Tools
|  Operator  | Description  |
|------------|------------- |  
| Duplicate Skin Part | Duplicates selected object and its collection into new collection (for faster clothes and skin part making) |
| Cleanup Rotation | Cleanup edit mode rotations and convert into object mode rotations |

### Texture Tools
|  Operator  | Description  |
|------------|------------- |
| Cuboid UV Unwrap | UV unwraps selected objects into similar format used by base game, with selectable front face |
| Pixel UV Unwrap | UV unwraps all faces into a square (so they can share a single pixel) |
| UV Pack | Automatic UV packing that preserves size ratios and clamps to pixel corners with adjustable UV island pixel padding |   
| Enable Material | Enable material face export |
| Disable Material | Disable material face export (disable faces by assigning disabled material) |
| Glow | Set object glow (sets glow on all faces on object) |

### Animation Tools
|  Operator  | Description  |
|------------|------------- | 
| Make Bones XZY | Set all bones in armature to XZY Euler (VintageStory format) |
| Auto Assign Bones | Assign selected objects parent to closest Armature bone |
| Step Parent Name | Set selected objects `stepParentName` |
| Assign Step Parent Constraint | Assigns bone constraint to object's step parent in Armature |
| Remove Step Parent Constraint | Removes bone constraint to Armature step parent |
| Rename on Export | Renames object on export (sometimes needed for proper animation or step parent mapping) |

### Export Tools
|  Operator  | Description  |
|------------|------------- | 
| Quick Export | Export scene using default settings in export menu and blender filename |
| Export Selected Collection | Exported selected object and its collection in scene |
| Export Highlighted Collections | Exported highlighted collections in View Layer menu |

Known Issues (TODO):
---------------------------------------
- Cannot UV export a cube converted into a plane by scaling a dimension to 0
  (e.g. single plane, such as for hair) does not work, need special case for uv
- Cannot properly export animations after rotating model 90 deg
  (need to carry and apply 90 deg rotations)
- Will not export bone with no child cubes (need to insert dummy cube)

# Migrating from old animation pose marker metadata
Old versions before 0.7.0 used pose markers to set animation metadata.
Newer version uses an N-panel gui and custom field stored on action objects.
To migrate old pose marker metadata, run the script below in the blender
file's scripting window, which adds the custom fields to action objects:

```python
import bpy

for action in bpy.data.actions:
    for marker in action.pose_markers:
        if marker.name.startswith("onActivityStopped_"):
            on_activity_stopped = marker.name[18:]
            action["on_activity_stopped"] = on_activity_stopped
        elif marker.name.startswith("onAnimationEnd_"):
            on_animation_end = marker.name[15:]
            action["on_animation_end"] = on_animation_end
```

blender-vintagestory-json

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README