Vulkan Schnee Blender Exporter Plugin

Blender plugin that extends the glTF 2.0 exporter with two custom extensions for Vulkan Schnee Engine data.

File: BlenderPlugins/ExporterPlugin/

Extensions

The exporter adds two glTF extensions:

VULKAN_SCHNEE_engine_properties

Per-object metadata attached to glTF nodes. Contains mesh behavior, lighting settings, and lightmap configuration.

VULKAN_SCHNEE_materials

Per-material shader configuration attached to glTF materials. Contains shader type, parameters, and PBR texture/factor data.

Installation

Install as a standard Blender addon via Edit > Preferences > Add-ons > Install.... Requires the io_scene_gltf2 addon (Blender's built-in glTF exporter).

Export Options

The plugin adds a "Vulkan Schnee Engine" panel to the glTF export dialog:

Option	Description
Export Preset	Selects a Vulkan Schnee export layout for Blender's standard glTF exporter. Use Load Preset to apply it to the active export dialog.
Export Engine Properties	Enables VULKAN_SCHNEE_engine_properties and VULKAN_SCHNEE_materials extensions. Default: enabled.
Validate Properties	Runs pre-export validation and logs issues to console. Default: enabled.
Copy Baked Lightmaps	Copies lightmaps/ folder from .blend directory to export directory. Default: disabled.

Export Presets

Open File > Export > glTF 2.0, choose a preset in the Vulkan Schnee Engine panel, then click Load Preset. The preset updates Blender's active glTF export options without replacing the standard export flow.

Preset	Purpose
Engine glTF	Separate .gltf runtime export with engine metadata, materials, UVs, normals, and tangents.
Engine External Textures	Separate glTF export with Images=None and copied PBR texture references.
Engine Lightmapped	Separate glTF export with copied PBR textures and baked lightmaps.

VULKAN_SCHNEE_engine_properties Extension

Exported for each mesh object. Reads properties from the editor plugin's vulkan_schnee_properties object attribute.

JSON Structure

{
  "version": "1.0.0",
  "meshProperties": {
    "isStatic": false,
    "collisionEnabled": true
  },
  "lightingProperties": {
    "castShadows": true,
    "receiveShadows": true,
    "hasLightmaps": false
  },
  "lightmapProperties": {
    "lightmapPath": "lightmaps/object_lightmap.hdr",
    "lightmapUvIndex": 1,
    "lightmapResolution": 1024,
    "lightOnly": false
  },
  "metadata": {
    "exportedFromBlender": true,
    "blenderObjectName": "Cube",
    "exportTimestamp": 1
  }
}

Fields

meshProperties:

• isStatic (bool) - Object does not move. Engine can optimize draw calls.
• collisionEnabled (bool) - Object has physics collision.

lightingProperties:

• castShadows (bool) - Object casts shadows.
• receiveShadows (bool) - Object receives shadows.
• hasLightmaps (bool) - Object has baked lightmap texture.

lightmapProperties (only present if hasLightmaps is true):

• lightmapPath (string) - Path to lightmap image relative to glTF file.
• lightmapUvIndex (int) - UV attribute index for lightmap coordinates (0-7). Typically 1 for TEXCOORD_1.
• lightmapResolution (int) - Lightmap texture resolution (e.g., 512, 1024).
• lightOnly (bool) - Lightmap contains only lighting (no albedo baked in).

Legacy Property Fallback

If vulkan_schnee_properties does not exist, the exporter checks for legacy custom properties:

• HasLightmaps → lightingProperties.hasLightmaps
• LightMapPath → lightmapProperties.lightmapPath
• LightMapUvIndex → lightmapProperties.lightmapUvIndex

Materials without properties get a basic metadata-only extension.

VULKAN_SCHNEE_materials Extension

Exported for each material. Reads shader node data from Vulkan Schnee shader nodes in the material's node tree.

File: BlenderPlugins/ExporterPlugin/MaterialExtension.py

JSON Structure

{
  "shaderType": "movableDiffuseShader",
  "shaderParameters": {
    "Base Color": {
      "type": "connected",
      "socketType": "RGBA"
    },
    "Normal Map": {
      "type": "value",
      "value": [0.5, 0.5, 1.0, 1.0],
      "socketType": "RGBA"
    },
    "Roughness Factor": {
      "type": "value",
      "value": 0.8,
      "socketType": "VALUE"
    }
  },
  "nodeProperties": {
    "sh_scale": 1.0,
    "ambient_term": 0.1,
    "debug_mode": 0,
    "tone_mapping": "REINHARD"
  },
  "pbrFactors": {
    "base_color_factor": [1.0, 1.0, 1.0, 1.0],
    "roughness_factor": 0.8,
    "metallic_factor": 0.0,
    "normal_scale": 1.0,
    "emissive_factor": [0.0, 0.0, 0.0]
  }
}

Shader Types

Shader types correspond to Vulkan Schnee shader nodes defined in the editor plugin:

Shader Type	Description	Debug Modes	Tone Mapping
diffuseFlatColor	Solid color	None	None
diffuseShader	Basic texture	None	None
movableDiffuseShader	Full PBR + SH lighting	0-5	Reinhard/ACES
normalsShader	Normal visualization	Fixed (1)	None
staticLightmap	Baked lightmap (UV2)	0-2, 6	Reinhard/ACES
l0Shader	SH L0 only (ambient)	Fixed (3)	None
l1Shader	SH L1 only (directional)	Fixed (4)	None
l2Shader	SH L2 only (quadratic)	Fixed (5)	None
dynamicTextures	Full PBR + SH (ACES)	0-5	ACES

Debug Modes:

• 0 - Normal rendering with tone mapping
• 1 - Normals as RGB (normal * 0.5 + 0.5)
• 2 - Raw SH values without tone mapping
• 3 - L0 term only (ambient)
• 4 - L1 terms only (directional)
• 5 - L2 terms only (quadratic)
• 6 - Lightmap UV coordinates

PBR Texture Export

The exporter automatically maps Vulkan Schnee shader node inputs to standard glTF PBR fields:

Texture Mappings:

VS Input Socket	glTF Field	glTF UV Attribute
Base Color	pbrMetallicRoughness.baseColorTexture	TEXCOORD_0
Roughness	pbrMetallicRoughness.metallicRoughnessTexture	TEXCOORD_0
Metallic	(same as Roughness)	TEXCOORD_0
Normal Map	normalTexture	TEXCOORD_0
Emissive	emissiveTexture	TEXCOORD_0
Lightmap Texture	(stored in extension only)	TEXCOORD_1

Factor Mappings:

VS Input Socket	glTF Field
Base Color (unconnected)	pbrMetallicRoughness.baseColorFactor
Roughness Factor	pbrMetallicRoughness.roughnessFactor
Metallic Factor	pbrMetallicRoughness.metallicFactor
Normal Scale	normalTexture.scale
Emissive Factor	emissiveFactor

glTF requires metallic and roughness in a single texture (green=roughness, blue=metallic). The exporter uses the roughness texture if both are connected. Separate metallic textures generate a warning.

Node Discovery

The exporter searches the material's node tree for Vulkan Schnee shader nodes:

1. Custom nodes with bl_idname starting with VulkanSchneeShader
2. Node groups with a shader_type custom property

If multiple nodes exist, the first is used. Materials without VS nodes get a default diffuseFlatColor shader with "defaulted": true in metadata.

Validation

When "Validate Properties" is enabled, the exporter runs pre-export checks:

Object Validation:

• Lightmaps enabled but no lightmapPath specified
• Invalid lightmapUvIndex (not 0-7)

Material Validation:

• Counts materials with Vulkan Schnee shaders
• Logs shader types to console

Validation warnings print to the Blender system console (Window > Toggle System Console on Windows).

Implementation Details

Export Hooks

The plugin implements the glTF2ExportUserExtension interface:

Hook	Purpose
gather_gltf_extensions_hook()	Registers extension names in extensionsUsed
gather_node_hook()	Exports VULKAN_SCHNEE_engine_properties per object
gather_material_hook()	Exports VULKAN_SCHNEE_materials per material
pre_export_hook()	Validates scene and logs statistics
post_export_hook()	Copies lightmap files to export directory

Lightmap Copying

When "Copy Baked Lightmaps" is enabled:

1. Looks for lightmaps/ folder next to the .blend file
2. Copies entire folder to export directory
3. Uses shutil.copytree() with dirs_exist_ok=True (overwrites existing)

Engine Import

The engine reads these extensions in GltfLoader.cpp:

VULKAN_SCHNEE_engine_properties:

GltfLoader::VulkanSchneeExtension extension(node.extensions["VULKAN_SCHNEE_engine_properties"]);
if (extension.hasLightmapProperties()) {
    // Load lightmap texture using lightmapPath and lightmapUvIndex
}

VULKAN_SCHNEE_materials:

GltfLoader::MaterialExtensions matExt(material.extensions);
if (matExt.hasVulkanSchneeMaterialExtension()) {
    std::string shaderType = matExt.vulkanSchneeMaterialExtension.shaderType;
    // Select pipeline based on shaderType
}

See GltfLoader for complete import implementation.

Development Workflow

After modifying exporter code:

. ./repo-commands.ps1
zip-plugin

This rebuilds the plugin zip for distribution. Reload the plugin in Blender to test changes.

Related Documentation

• Editor Plugin - Defines the shader nodes that the exporter reads
• glTF Loader - Engine-side import of these extensions