Skip to content

Vertex Painting & Post Processing

Jump to bottom
FireRat edited this page Jun 27, 2026 · 2 revisions

Vertex Painting & Post-Processing

Reference for procedural vertex coloring, geometry optimization, lightmap UV generation, collider creation, and all other post-processing features available in the Post-Processing panel.

Overview

Post-processing runs automatically at the end of every full maze generation, in a fixed sequential pipeline. All post-processing is skipped during interactive editing (incremental rebuilds bypass it for instant response). Exiting edit mode triggers a full rebuild with all post-processing applied.

1. Vertex Painting

Post-Processing panel — vertex_paint_enable, vertex_paint_mode, vertex_paint_intensity

Procedurally paints vertex colors on maze meshes for shading, texturing, or game engine blending. Operates on final visual meshes (FireMaze_Merged or individual floor/wall/roof objects depending on merge settings).

Common Behavior

  • Creates or updates a loop float color layer named "Color".
  • Each vertex maps to a cell (via world-coordinate grid alignment) and a floor level (via Z-height).
  • Intensity (vertex_paint_intensity, 0.0–1.0) scales the effect opacity.
  • Vertex painting is applied after coplanar optimization (if enabled) and before lightmap UV generation.

Ambient Occlusion Mode

vertex_paint_mode = 'ao'

Darkens corners, seams, and floor/roof boundaries for a natural shadowed look.

Factor Calculation
Floor proximity Distance from vertex Z to bounding-box floor, clamped to 0.15 × tile_size.
Roof proximity Distance from vertex Z to bounding-box roof, same seam width.
Corner distance Grid-aligned corner distance — for rect: distance from (px, py) to nearest integer grid intersection; for polar: distance from (R, phi) to nearest ring/sector boundary.
Final AO max(floor_factor, roof_factor, corner_factor) reduced by intensity × 0.7.

Texture Blend Weights Mode

vertex_paint_mode = 'blend'

Encodes material blend weights across RGBA channels for shader-driven texturing.

Channel Label Calculation
R Moss Proximity to floor: max(0, 1 - h/0.25) where h is relative height within the floor level.
G Cracks Proximity to nearest grid corner / seam (0.15 × tile_size radius).
B Wetness 1.0 on near-horizontal faces (normal.z > 0.9) within 2% of floor; fades linearly to 5% height.
A Soot 1.0 in dead-end cells (excludes entrances, exits, and stair cells), 0.0 elsewhere.

Dead-end detection scans all open cells and counts accessible neighbors (via wall flags for thin mode, cell [0] flag for cube mode). Cells with exactly one open neighbor (and not a stair, entrance, or exit) are marked as soot zones.

Path Highlight Mode

vertex_paint_mode = 'path'

Highlights floor tiles along the shortest BFS path from entrance to exit/center in green.

  • Converts maze_data.guide_path coordinates to world positions (cell centers).
  • For each vertex, finds the minimum distance to any guide path cell center.
  • Within a 0.75 × tile_size radius, applies green with falloff: G = (1 - d/radius) × intensity.
  • Vertices outside the radius remain white.

Distance Gradient Mode

vertex_paint_mode = 'distance'

Black-to-white gradient mapped by BFS distance from the entrance.

  • Precomputes _compute_grid_distances(maze_data, wall_mode) for all cells.
  • Normalizes each cell's distance by the maximum distance in the maze.
  • Applies val = normalized_distance × intensity to all RGB channels.
  • Provides a heatmap-style visualization of path length from the entrance.

2. Merge Options

Post-Processing panel

Controls how the generated mesh objects are combined.

Single Wall Object

single_wall_object — Toggle, default ON

When enabled, all wall faces and wall-end cap faces are merged into a single FireMaze_Walls object. The outliner stays cleaner with one wall object instead of separate wall and cap objects.

Merge Objects

merge_objects — Toggle, default OFF

Combines floors, walls, roofs, and caps into a single merged mesh object named FireMaze_Merged. Useful for exporting a single mesh to game engines.

When enabled:

  1. All mesh objects in the maze collection are collected.
  2. _merge_maze_objects selects all of them and calls bpy.ops.object.join().
  3. The merged object replaces the individual objects.

3. Remove Doubles

remove_doubles — Toggle, default OFF

Performs a vertex weld operation on all generated mesh objects. Calls bmesh.ops.remove_doubles with a merge distance of 0.001 Blender units. This merges touching corners, stacked tiled wall segments, and any vertices that were split during mesh construction.

Runs before merge operations — when both Remove Doubles and Merge Objects are enabled, doubles are removed from individual objects first, then the merge joins them.

4. Lightmap UV Generation

Post-Processing panel — generate_lightmap, lightmap_method

Generates a second UV map named "Lightmap" on all final visual mesh objects for baking or lightmapping in game engines. Operates via Blender's native UV operators.

Smart UV Project

lightmap_method = 'smart'

Groups adjacent/co-planar faces into contiguous UV islands. Recommended for reducing seam-bleeding in game engines. Uses Blender's Smart UV Project operator with default settings.

Lightmap Pack

lightmap_method = 'pack'

Projects and packs each face individually. Guarantees zero distortion and maximum packing efficiency, but splits every face into its own UV island. Uses Blender's Lightmap Pack operator.

Technical Notes

  • UV generation runs after vertex painting — painted vertex colors are preserved.
  • An existing "Lightmap" UV layer is reused if present; otherwise a new one is created.
  • The active UV map is temporarily switched to "Lightmap" during generation, then restored. The original UV map (typically "UVMap") is preserved as the first UV layer.

5. Planar Dissolve

Post-Processing panel — optimize_coplanar

Simplifies mesh geometry by dissolving coplanar faces. Reduces polygon count for better performance in game engines or rendering.

Process

  1. Remove doubles first (merge distance 0.001) so adjacent faces share edges and vertices.
  2. Limited dissolve (bmesh.ops.dissolve_limit) with an angle limit of 0.5°.

Warning

Planar dissolve may stretch or break seamless tiled textures because it merges faces across grid boundaries. A warning is displayed in the UI when this option is enabled. Use with custom-unwrapped or unique textures rather than tiled repeating textures.

6. Collider Generation

Post-Processing panel — generate_colliders, merge_colliders, optimize_colliders_coplanar

Generates simple, flat-faced helper meshes matching the maze layout for easy game engine integration.

How It Works

Colliders are built by calling build_maze_objects(props, maze_data, context, collection=col, force_simple=True, name_suffix="_Collider"). This re-runs the full maze builder (floor, walls, roof, stairs) with force_simple=True, producing simplified flat-faced geometry without custom meshes or complex UVs.

Collider Objects

Object Name Description
FireMaze_Floor_Collider Flat floor collider mesh
FireMaze_Walls_Collider Wall collider mesh
FireMaze_Roof_Collider Roof collider mesh

All collider objects are:

  • Hidden from renders (hide_render = True).
  • Set to wireframe display (display_type = 'WIRE') for easy visualization.
  • Tagged with the fire_maze custom property for scene cleanup.

Note: Roof colliders are generated even when Instanced Pillars (Pillar Mode) is enabled, ensuring collision meshes exist for the entire maze volume.

Merge Colliders

merge_colliders — Toggle, default OFF

When enabled, all individual collider objects are joined into a single FireMaze_Collider mesh via _merge_maze_objects. The merge runs after individual coplanar optimization if both are enabled.

Optimize Colliders

optimize_colliders_coplanar — Toggle, default OFF

Applies _optimize_coplanar_on_obj (planar dissolve, 0.5° angle limit) to collider meshes. When both Merge and Optimize are enabled:

  1. Each collider object is optimized individually.
  2. The optimized colliders are merged into FireMaze_Collider.
  3. The merged collider is optimized again.

7. Execution Order

The full post-processing pipeline runs in sequence at the end of every maze generation (inside build_maze_objects_impl, after all mesh objects are built):

1. Remove Doubles          (if enabled, on all generated objects)
2. Merge Walls/Caps        (if Single Wall Object enabled)
3. Merge All Objects       (if Merge Objects enabled)
4. Optimize Coplanar       (if enabled, on final visual meshes)
5. Vertex Painting         (if enabled, on final visual meshes)
6. Lightmap UV Generation  (if enabled, on final visual meshes)
7. Prop/Decor Spawning     (if any prop meshes assigned)
8. Collider Generation     (if enabled, separate build pass)

Interactive Edit Mode

During interactive editing:

  • Steps 4–8 are completely skipped.
  • Only the basic mesh geometry is rebuilt incrementally.
  • Exiting edit mode triggers rebuild_maze_from_collection(), which runs the full pipeline.

8. UI Reference

Panel: VIEW3D_PT_fire_maze_cleanup — Post-Processing

Control Property Type Default
Single Wall Object single_wall_object Toggle ON
Merge Objects merge_objects Toggle OFF
Remove Doubles remove_doubles Toggle OFF
Generate Lightmap UVs generate_lightmap Toggle OFF
Method lightmap_method Enum (Smart UV Project / Lightmap Pack) Smart UV Project
Optimize Geometry (Dissolve Planar) optimize_coplanar Toggle OFF
Enable Vertex Painting vertex_paint_enable Toggle OFF
Vertex Paint Mode vertex_paint_mode Enum (AO / Blend / Path / Distance) AO
Paint Intensity vertex_paint_intensity Float 0.0–1.0 1.0
Generate Colliders generate_colliders Toggle OFF
Merge Colliders merge_colliders Toggle OFF
Optimize Colliders optimize_colliders_coplanar Toggle OFF

Clone this wiki locally