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 AirHockey/Blender/pythonScripts/plugin/

UI Panels

The plugin adds three panels to Blender's interface:

3D Viewport Sidebar Panel

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

Lighting Section:

• Automated Lightmap Setup - One-click lightmap workflow (creates UV channel, unwraps, configures properties)
• Pack UVs with Unwrella - Professional UV packing (requires UnwrellaConnect addon)
• Create Lightmap UV Channel - Creates "LightmapUV" channel on selected objects
• Bake Lightmaps - Bakes lightmaps using scene settings
• Diagnose Lightmap Issues - Validates lightmap configuration
• Validate Lightmaps - Checks UV maps for all objects with lightmaps enabled
• Set All Lightmap Resolutions - Batch resolution update
• Bake Volume SH - Bakes spherical harmonics for volume

Cubemap Section:

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

Dependencies Section:

• Shows scipy/numpy installation status
• Install Dependencies - Installs required Python packages (scipy, numpy) into Blender's Python environment

Export Section:

• Export GLTF with Vulkan Schnee Extension - Exports GLTF with custom material data
• Analyze Materials - Reports Vulkan Schnee shader usage and validation issues
• List Material Data - Shows export data for each material
• Show Integration Help - Prints engine integration guide to console

Migration Tools Section:

• Migrate Custom Properties - Converts old custom properties to new property system

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:

• Static Lightmap (UV2) - Baked lightmaps using TEXCOORD_1
• L0 Lightmap - L0 spherical harmonics term only
• L1 Lightmap - L1 spherical harmonics terms only
• L2 Lightmap - L2 spherical harmonics terms only

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 (Color) - Emissive color multiplier
• SH Scale (Float) - Spherical harmonics coefficient scaling (default 0.15)
• 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
• Normal Map (Color) - Normal map
• Roughness (Float) - Roughness texture
• Metallic (Float) - Metallic texture
• Emissive (Color) - Emissive texture
• PBR factors (same as Movable Diffuse)
• 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

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

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 Unwrella Packing: Professional UV packing (requires UnwrellaConnect addon)
• UV Padding (px): Padding between islands (0-32, default 2.0)

Standard Unwrapping Parameters (if not using Unwrella):

• 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 (Smart UV Project or Unwrella)
   • Sets object properties (has_lightmaps, resolution, UV index)
   • Reports success/errors per object

Unwrella Integration:

If UnwrellaConnect addon is installed and enabled:

• Objects are grouped by resolution
• Each group packed separately with pixel-perfect density
• UV channel set to "LightmapUV"
• Unwrella settings auto-configured (rescale, prerotate, 90° rotation allowed)

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

Exports GLTF with VULKAN_SCHNEE_materials extension. Material data includes:

Per Material:

• shaderType - Shader identifier (e.g., "movableDiffuseShader")
• shaderParameters - Input socket data:
  • Connected inputs: ‘{type: 'connected’, socketType: 'NodeSocketColor'}
  • Value inputs: {type: 'value', value: [1.0, 0.5, 0.3, 1.0], socketType: 'NodeSocketColor'}
• 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'
• 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: 6

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)
   • Enable "Use Unwrella Packing" if installed
   • Execute
3. Material Setup:
   • For each material, add "VS Static Lightmap" shader node
   • 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" (Schnee Engine panel)
   • Lightmaps saved to object.vulkan_schnee_properties.lightmap_path
5. Export:
   • File > Export > GLTF with Vulkan Schnee Data
   • Choose GLB format
   • Engine loads GLTF with lightmap data

Spherical Harmonics Baking

For dynamic objects that need ambient lighting:

Volume SH Baking (object.vulkanschnee_bake_volume_sh):

• Bakes SH coefficients at object origin
• Creates empty named "SH_Volume_[ObjectName]"
• Stores L0, L1, L2 coefficients as custom properties
• Used by "VS Movable Diffuse" shader 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 AirHockey/Blender/pythonScripts/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 - GLTF export extension
• 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