Vulkan Schnee Blender Editor

Blender plugin for creating game-ready assets for the Vulkan Schnee Engine. Adds custom panels, shader nodes, and export tools.

Requirements: Blender 4.0+

Installation: See BlenderPlugins/plugin/

UI Panels

The plugin adds panels to Blender's interface:

3D Viewport Sidebar Panel

Location: 3D Viewport > Sidebar (N) > Vulkan Schnee Engine

Scene Setup:

• Fix 0.01 Scales - Detects and fixes imported scale issues
• Apply Scale to Selected - Applies object scale on selected objects
• Migrate Custom Properties - Converts legacy object custom properties to the property group
• Batch Edit Properties - Batch-edits engine object properties
• Batch Reset Lightmap Fields - Clears lightmap EXR and KTX path fields
• Upgrade Shader Nodes - Upgrades selected-object material nodes

Materials:

• Analyze Materials - Reports Vulkan Schnee shader usage and validation issues
• List Export Data - Shows export data for each material
• Convert Material to VS Shader - Converts active material setup to a Vulkan Schnee shader node
• Show Integration Help - Prints engine integration guide to console

Lightmapping > Setup:

• Automated Lightmap Setup - One-click lightmap workflow
• Create Lightmap UV Channel - Creates LightmapUV on selected objects
• Rename UV to LightmapUV - Renames an existing UV layer by index
• Pack Selected LightmapUVs with xatlas - Packs existing LightmapUV islands with xatlas
• Select Problematic LightmapUV Geometry - Selects UV geometry that fails validation
• Generate Selected LightmapUVs - Generates and packs LightmapUV with xatlas

Lightmapping > Baking:

• Bake Lightmaps - Bakes lightmaps using scene settings
• Rent Workers + Bake - Starts distributed lightmap baking
• Set All Lightmap Resolutions - Batch resolution update
• Bake SH in Volumes - Bakes spherical harmonics probes inside volume meshes

Lightmapping > Validation:

• Validate Lightmaps - Checks UV maps for all objects with lightmaps enabled
• Diagnose Lightmap Issues - Validates lightmap configuration

Export:

• Select Exportable - Selects mesh objects that will be exported
• Select Collision Meshes - Selects VSC_ collision meshes
• Hide Collision from Render - Excludes collision helpers from render/export
• Organize Collision Collections - Moves collision helpers into collision collections
• Export glTF - Convenience wrapper around Blender glTF export; engine data is written by the separate exporter add-on in BlenderPlugins/ExporterPlugin/

Cubemaps:

• Create Cubemap Camera Rig - Sets up 6 cameras for cubemap rendering
• Render Cubemap - Renders cubemap from camera rig

UV Editor Sidebar Panel

Location: UV Editor > Sidebar (N) > Schnee > xatlas Packing

• Texture Resolution: 256, 512, 1024, 2048, or 4096
• UV Padding (px): Pixel margin between islands
• High Quality Packing: Uses slower xatlas placement for better utilization
• Block Align: Aligns charts to 4x4 texel blocks for block-compressed textures
• Repack Active UV - Packs the active UV map on selected mesh objects

Dependencies Panel

Location: 3D Viewport > Sidebar (N) > Vulkan Schnee Engine > Dependencies

• Shows SciPy and OIDN installation status
• Install Dependencies - Installs required Python packages into Blender's Python environment

Object Properties Panel

Location: Properties > Object Properties > Vulkan Schnee Engine

Appears for mesh objects only. Configures per-object engine properties.

Mesh Properties:

• Static Mesh - Mark as static for optimization
• Enable Collision - Toggle collision detection

Lighting:

• Cast Shadows - Whether mesh casts shadows
• Receive Shadows - Whether mesh receives shadows

Lightmaps:

• Has Lightmaps - Enable lightmap baking for this object
• Lightmap Resolution - Texture resolution (64-4096, default 1024)
  • Preset buttons: 512, 1K, 2K, 4K
• Lightmap Path - File path to lightmap texture
• Lightmap UV Index - UV channel index (0-7)
• Light Only - Bake pure lighting data without tonemapping

Panel validates UV maps and shows warnings for missing lightmap paths.

Scene Properties Panel

Location: Properties > Scene Properties > Lightmap Settings

Global lightmap baking configuration.

Quality Settings:

• Quality Preset - Draft (32), Preview (128), Production (512), Ultra (1024), Custom
• Bake Samples - Sample count for baking (1-4096)
• Use Denoiser - Enable Blender's denoiser

Shader Editor Panel

Location: Shader Editor > Sidebar (N) > Vulkan Schnee

Appears when editing material shader nodes.

Add Vulkan Schnee Nodes - Creates preconfigured PBR shader setup

Vulkan Schnee Shaders:

Basic Shaders:

• Diffuse Flat Color - Renders flat color with preview support
• Diffuse - Basic texture sampling
• Movable Diffuse - Full SH lighting with tone mapping
• Normals - Visualizes normals as colors

Lightmap Shaders:

• L0 Lightmap - L0 spherical harmonics term only
• L1 Lightmap - L1 spherical harmonics terms only
• L2 Lightmap - L2 spherical harmonics terms only

Static Lightmap (UV2) is available from Shader Editor > Add > Vulkan Schnee Shaders > Lightmap Shaders, not from the Shader Editor sidebar panel.

Advanced:

• Dynamic Textures - Full SH + ACES tone mapping

Shader Nodes

All Vulkan Schnee shader nodes are implemented as Blender node groups for viewport preview support. They export custom material data via glTF extensions.

VS Diffuse Flat Color

Simple flat color shader. Renders as Diffuse BSDF in Blender viewport.

Inputs:

• Color (RGBA) - Flat color value

Properties:

• Node group version tracked
• Exports as shaderType: "diffuseFlatColor"

Usage:

Add > Vulkan Schnee Shaders > Diffuse Flat Color
Set color value or connect texture
Connect BSDF output to Material Output

VS Diffuse

Basic texture sampling shader.

Inputs:

• Base Color (Color) - Color texture input

Exports as: shaderType: "diffuseShader"

VS Movable Diffuse

Full-featured spherical harmonics lighting with PBR inputs.

Inputs:

• Base Color (Color) - Albedo texture
• Normal Map (Color) - Normal map texture
• Roughness (Float) - Roughness texture
• Metallic (Float) - Metallic texture
• Emissive (Color) - Emissive texture
• Roughness Factor (Float) - Multiplier for roughness (0-1)
• Metallic Factor (Float) - Multiplier for metallic (0-1)
• Normal Scale (Float) - Normal map intensity
• Emissive Factor (Float) - Emission strength multiplier
• SH Scale (Float) - Spherical harmonics coefficient scaling (default 1.0)
• Ambient Term (Float) - Constant ambient lighting (default 0.1)
• Debug Mode (Int) - Visualization mode (0=normal, 1=normals, 2=raw SH, 3-5=L0-L2 only)
• Tone Mapping (Int) - Algorithm (0=Reinhard, 1=ACES)

Exports as: shaderType: "movableDiffuseShader"

Preview: Uses Principled BSDF with normal map node

VS Normals

Visualizes surface normals as RGB colors. Matches shader formula: normal * 0.5 + 0.5

No inputs - Auto-generates from geometry normals

Exports as: shaderType: "normalsShader" with debug_mode: 1

Preview: Geometry node → Vector Math (scale 0.5) → Vector Math (add 0.5) → Diffuse BSDF

VS Static Lightmap

For static objects with baked lightmaps using UV2 (TEXCOORD_1).

Inputs:

• Base Color (Color) - Albedo texture
• Lightmap Texture (Color) - Baked lightmap sampled with UV2
• Alpha (Float) - Alpha channel for alpha mask support
• Normal Map (Color) - Normal map
• Roughness (Float) - Roughness texture
• Metallic (Float) - Metallic texture
• Emissive (Color) - Emissive texture
• PBR factors (same as Movable Diffuse; Emissive Factor is Float)
• SH Scale (Float) - Fallback SH ambient
• Ambient Term (Float) - Additional ambient
• Debug Mode (Int) - 0=normal, 1=normals, 2=raw lightmap, 6=UV2 visualization
• Tone Mapping (Int) - Algorithm
• Render Mode (Int) - 0=opaque, 1=alpha mask
• Alpha Cutoff (Float) - Alpha test threshold when Render Mode is 1

Exports as: shaderType: "staticLightmap"

Preview: Multiplies Base Color × Lightmap Texture, feeds to Principled BSDF

VS L0/L1/L2 Lightmap

Spherical harmonics debug shaders. Show only specific SH terms.

Inputs:

• Base Color (Color) - Color texture
• SH Scale (Float) - Scaling for specific term
• Ambient Term (Float) - Additional ambient

Exports as:

• L0: shaderType: "l0Shader", debug_mode: 3
• L1: shaderType: "l1Shader", debug_mode: 4
• L2: shaderType: "l2Shader", debug_mode: 5

VS Dynamic Textures

Advanced shader with full SH lighting and PBR support. Uses ACES tone mapping by default.

Inputs: Same as VS Movable Diffuse plus Alpha, Render Mode, and Alpha Cutoff. Dynamic Textures uses ACES tone mapping by default and does not expose a Tone Mapping input in the node group.

Exports as: shaderType: "dynamicTextures"

Difference from Movable Diffuse: ACES tone mapping is default

Automated Lightmap Setup

One-click lightmap workflow. Processes selected mesh objects.

Operator: object.vulkanschnee_automated_lightmap_setup

Dialog Options:

Resolution Settings:

• Resolution Preset: 512, 1024 (1K), 2048 (2K), 4096 (4K), Custom
• Custom Resolution: 64-8192 (if Custom selected)

Options:

• Enable Lightmaps: Toggle lightmap properties
• Lightmap Only: Enable light-only baking (no albedo/textures)
• Use Existing UV: Reuse existing LightmapUV channel if present

UV Packing:

• Use xatlas Packing: Pack LightmapUV islands with the bundled xatlas CLI
• UV Padding (px): Padding between islands (0-64, default 4)
• High Quality Packing: Use xatlas brute-force placement for better utilization
• Block Align: Align charts to 4x4 texel blocks for block-compressed lightmaps

Initial Unwrapping Parameters:

• Angle Limit: Smart UV unwrap angle limit (radians, default ~66°)
• Island Margin: Margin between UV islands (0-1, default 0.02)

Workflow:

1. Select mesh objects
2. Run operator (shows dialog)
3. Choose resolution preset
4. Enable/disable options
5. Execute:
   • Creates "LightmapUV" channel on each object
   • Unwraps UVs with Smart UV Project when a new layout is needed
   • Packs UV islands with xatlas using the requested pixel padding
   • Sets object properties (has_lightmaps, resolution, UV index)
   • Reports success/errors per object

xatlas Integration:

The plugin builds vksch_xatlas_uv_packer on demand via CMake from https://github.com/jpcy/xatlas.

• Works without a paid Blender addon
• Objects are grouped by resolution for processing
• Each object remains packed into its own 0-1 lightmap UV space
• The LightmapUV channel is written directly after the CLI returns packed coordinates

Material Analysis

Validates materials for engine compatibility.

Analyze Materials (vulkanschnee.analyze_materials):

• Counts total materials and Vulkan Schnee materials
• Groups by shader type
• Reports validation issues

List Export Data (vulkanschnee.list_material_data):

• Shows glTF export data for each material
• Displays shader type and parameters
• Shows connected vs value inputs

Validation Issues Detected:

• Multiple shader output nodes in one material
• Pure white colors (may be unintended)
• Missing texture connections for texture-based shaders
• Missing lightmap textures for lightmap shaders
• Disconnected critical inputs

glTF Export

Operator: export_scene.vulkanschnee_gltf

Runs Blender's glTF exporter from the editor add-on. The actual VULKAN_SCHNEE_materials, VULKAN_SCHNEE_engine_properties, and VULKAN_SCHNEE_asset_metadata extensions are exported by the separate add-on in BlenderPlugins/ExporterPlugin/.

Material extension data includes:

Per Material:

• shaderType - Shader identifier (e.g., "movableDiffuseShader")
• shaderParameters - Input socket data:
  • Connected inputs: ‘{type: 'connected’, socketType: 'RGBA'}
  • Value inputs: {type: 'value', value: [1.0, 0.5, 0.3, 1.0], socketType: 'RGBA'}
  • Float inputs: {type: 'value', value: 0.0, socketType: 'VALUE'}
• nodeProperties - Shader-specific controls:
  sh_scale (Float) - SH scaling factor
  ambient_term (Float) - Ambient lighting
  debug_mode (Int) - Debug visualization mode
  tone_mapping‘ (String) - 'REINHARD’ or 'ACES'
  • render_mode (Int) - 0=opaque, 1=alpha mask
  • alpha_cutoff (Float) - Alpha mask cutoff when render_mode is 1
• customProperties - Material custom properties with vulkan_schnee_ prefix

Export Options:

• Format: GLB, glTF Embedded, glTF Separate
• Standard glTF export settings available

Migration Tools

Migrate Custom Properties (object.vulkanschnee_migrate_custom_properties):

Converts old custom properties to new property system:

• HasLightmaps → vulkan_schnee_properties.has_lightmaps
• LightMapPath → vulkan_schnee_properties.lightmap_path
• LightMapUvIndex → vulkan_schnee_properties.lightmap_uv_index

Processes all mesh objects in scene. Backward compatibility maintained via fallback in GameEngineProperties.get_property_from_object().

Node Versioning

All node groups track version via vs_node_version custom property.

Current Version: 9

Version Operators:

Check Versions (node.vulkanschnee_check_versions):

• Scans all materials
• Reports outdated nodes
• Prints version info to console

Upgrade Old Nodes (node.vulkanschnee_upgrade_nodes):

• Converts old custom nodes to node groups
• Updates outdated node group versions
• Preserves connections and values
• Maps old socket names to new (e.g., "Color" → "Base Color")

Cleanup Orphaned Data (node.vulkanschnee_cleanup_orphaned):

• Removes unused node groups with shader_type property
• Only removes if user count is 0

Property Access API

For backward compatibility with old custom properties:

from . import GameEngineProperties
 
# Get property with fallback to custom properties
has_lightmaps = GameEngineProperties.get_property_from_object(
    obj, "HasLightmaps", default_value=False
)

Property mapping:

• HasLightmaps → has_lightmaps
• LightMapPath → lightmap_path
• LightMapUvIndex → lightmap_uv_index

Engine Integration

See EngineIntegration.py for shader name mapping:

Blender to Engine:

ENGINE_SHADER_MAPPING = {
    "diffuseFlatColor": "diffuseFlatColor",
    "diffuseShader": "diffuseShader",
    "movableDiffuseShader": "movableDiffuseShader",
    "normalsShader": "normalsShader",
    "staticLightmap": "staticLightmap",
    "l0Shader": "l0Shader",
    "l1Shader": "l1Shader",
    "l2Shader": "l2Shader",
    "dynamicTextures": "dynamicTextures"
}

Show Integration Help (vulkanschnee.show_integration_help):

• Prints engine integration code examples to console
• Shows materialNameFromString() implementation
• Provides JSON processing examples
• Explains specialization constants usage

Lightmap Baking Workflow

Complete lightmap workflow for static scenes:

1. Scene Setup:
   • Add lights to scene
   • Position objects
2. Lightmap Setup:
   • Select static mesh objects
   • Run "Automated Lightmap Setup"
   • Choose resolution (1K standard, 2K for important objects)
   • Keep "Use xatlas Packing" enabled for pixel-margin UV packing
   • Execute
3. Material Setup:
   • For each material, add Static Lightmap (UV2) from Shader Editor > Add > Vulkan Schnee Shaders > Lightmap Shaders
   • Connect base color textures
   • Connect PBR maps (normal, roughness, metallic)
   • Connect shader BSDF output to Material Output
4. Baking:
   • Configure scene lightmap settings (Scene Properties > Lightmap Settings)
   • Select objects to bake
   • Run Bake Lightmaps from Vulkan Schnee Engine > Lightmapping > Baking
   • Lightmaps saved to object.vulkan_schnee_properties.lightmap_path
5. Export:
   • Use File > Export > glTF 2.0
   • Choose glTF Separate format
   • Engine loads glTF with lightmap data

Spherical Harmonics Baking

For dynamic objects that need ambient lighting:

Bake SH in Volumes (scene.vulkanschnee_bake_volume_sh):

• Places probes inside meshes in the ProbeVolumes collection
• Bakes L0, L1, and L2 spherical harmonics per probe
• Writes sh_coeffs/probes.shprobe
• Used by VS Movable Diffuse and other SH-capable shaders at runtime

Debugging Tools

Debug Selected Shader Nodes (node.vulkanschnee_debug_shader_nodes):

• Prints detailed node information to console
• Shows inputs/outputs with values
• Shows connections
• Shows custom properties
• Prints programmatic node creation code

Test Export Data (node.vulkanschnee_test_export):

• Shows export data for active material
• Prints JSON to console
• Validates export before full scene export

Source Files

Plugin modules in BlenderPlugins/plugin/:

• __init__.py - Main registration, panel definitions
• GameEngineProperties.py - Object properties panel and property group
• LightmapSettings.py - Scene lightmap settings panel
• VulkanSchneeShaderNodes.py - Shader node definitions and node groups
• LightmapAutomation.py - Automated lightmap setup operator
• LightBaking.py - Lightmap baking implementation
• SphericalHarmonicsBaking.py - Volume SH baking
• GltfVulkanSchneeExtension.py - Editor-side glTF export helper; the glTF export extension lives in BlenderPlugins/ExporterPlugin/
• MaterialAnalyzer.py - Material validation and analysis
• EngineIntegration.py - Engine integration helpers
• CubemapHelper.py - Cubemap rendering tools
• GenerateMeshSettings.py - Mesh configuration
• SelectionHelper.py - Selection utilities
• CopyWithDebugMaterial.py - Debug material tools
• LoosePartMerger.py - Merge loose mesh parts
• LoosePartDebugMaterial.py - Debug materials for loose parts
• PrepareBakedExport.py - Export preparation