VS Blender World Importer

A Blender add-on that automates the collection assignment, mesh optimization, and material configuration of .obj world exports generated by the Vintage Story World Exporter (WExporter).

Could be combined with VS Blender Shape Importer for creating animations, anything really.

Includes a semi stylized PBR shader via a color averaging method. We assume specularity and shadow detail is painted to the VS textures. We extract the so called "pbr" detail from the textures by difference keying them versus a regional average.

Import Configuration Options

• Setup Viewport: Reconfigures the active 3D Viewport settings. It switches shading to Flat light mode, sets color type to Texture, hides object outlines, and activates Cavity shading using the "Both" type option (Ridge factor: 0.8, Valley factor: 2.5). It also overrides the viewport clipping distances to start at 0.4 and end at 512.0 units.

• Setup Optimized Rendering: Switches the active scene render engine to Cycles and sets both the scene and compositor processing devices to GPU. Adjusts performance settings to a maximum sample count of 256 (16 preview samples, adaptive threshold 0.075), forces Blue Noise sampling, and sets global illumination bounce limits (Max: 4, Diffuse: 2, Glossy: 1, Transmission: 4, Transparent: 16). Disables reflective and refractive caustics.

• Setup Vegetation Wind Pins: Analyzes imported plant meshes (opaquenocull) using a bmesh step-by-step stack to group connected geometry islands. It isolates the highest two vertices on the Y-axis for each geometric card and assigns them to a newly generated vertex group named "windpins" with a fixed weight of 1.0. (You can displace these via geo nodes or modifiers to get a nice wind effect)

• Setup Simple World Lighting: Clears all existing nodes in the World shader tree. It adds a Sky Texture node configured to an altitude of 2,000 meters, a 2.0-degree sun size, and a 30-degree sun rotation, routing it through a Background shader node set to a default strength of 0.2.

• Setup Color Avg: Parses the source block atlas image array through a structural NumPy array reshaping process using a 4x4 grid resolution. It runs a Breadth-First Search (BFS) region-growing routine to group similar color blocks within a 0.12 tolerance range, calculates their alpha-weighted average RGB values, updates the alpha profile, and writes a flat color map (_Col_avg.png) to disk to link into the material node group.(This is required for semi PBR shader setup thats included with the addon)

Modded Game Support & Configuration (for World Exporter)

The add-on handles modded block structures and customized textures. For heavily modded installations, the scale of assets can exceed default exporter boundary parameters, resulting in texture corruption or overlapping. You must manually raise the maximum atlas dimension limits within your local client configuration prior to rendering out world files.

Required adjustment:

1. Navigate to your local vintagestorydata folder.

2. Open clientsettings.json using a text editor.

3. Edit the maxTextureAtlas variables to be:

"maxTextureAtlasWidth": 8192,
"maxTextureAtlasHeight": 4096

Compatibility

• Blender Version: 5.0.0 or higher.

Installation Instructions

1. Download the VSBL_World_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_World_Importer.zip file, then click Install Add-on.

(You can now access the importer via File > Import > VS Wexporter (.obj)

Todo / Missing:

• VS like clouds geo nodes system.

• Liquid flow.
• Stars and square sun/moon.
• Distance random voxel terrain or farseer like LOD system.

• Eevee support.