BMixer+ Documentation

Advanced Material Mixer & Painter for Blender

BMixer+ is a powerful addon for Blender that enables a sophisticated layer-based workflow for creating complex PBR materials. It features advanced triplanar projection (eliminating the need for manual UVs for content textures), intricate blending options, anti-tiling solutions, and an intuitive "Brush Mode" for painting layer visibility directly onto your models.

BMixer+ Feature Breakdown

Core Workflow & Material System

• Layer-Based Texturing: Build complex materials by stacking layers, just like in Photoshop or Substance Painter.
• Non-Destructive: All your settings are saved with the material. You can go back and change any layer or setting at any time without losing work.
• Triplanar Projection Engine: Automatically projects textures onto your model from all sides, eliminating UV stretching and seams on complex objects.
• Dual Engine Choice:
  • Simple Engine: Faster performance, good for initial look development.
  • Advanced Engine: Higher quality blending between projected textures, removing blurry transitions.
• Real-Time Sync: See changes instantly as you adjust sliders and settings. This can be toggled off for better performance on very complex materials.
• Manual Apply/Rebuild: Manually apply pending changes or completely rebuild the material nodes with a single click to ensure a clean state.

Layer Control & Blending

• Easy Layer Management: Add, remove, rename, reorder, and hide/unhide layers in the stack.
• Procedural Layer Masking: Blend layers together using a built-in procedural noise mask. Create realistic wear, dirt, and damage effects.
  • Full control over noise: Scale, Detail, Roughness, and Distortion.
  • Control mask appearance with Threshold, Smoothness, Seed, and Invert.
• Selective Blending: Make a layer affect only specific layers below it. For example, make scratches appear only on a "Paint" layer, revealing a "Metal" layer underneath.
• Brush Mode (Texture Painting):
  • Paint a layer's visibility directly onto the model for ultimate artistic control.
  • Automatically creates the necessary UV maps and image masks for you.
  • Option to automatically Smart UV Project the model for optimal painting space.
  • Paint with white to reveal the layer, black to hide it.
• Opacity Control: Adjust the overall transparency of each layer.

Texture & PBR Features

• Full PBR Support: Control Base Color, Metallic, Roughness, Normal, Displacement (Height), Ambient Occlusion, and Emission for each layer.
• Auto-Assign PBR Textures: Select a group of PBR images, and the addon will automatically assign them to the correct slots based on their file names (e.g., rock_color.png, rock_normal.png).
• Per-Layer Transforms: Independently control the Scale, Location, and Rotation of textures on every layer.
• Color Tinting: Easily apply a color tint to any layer's Base Color texture for quick variations.
• IOR Control: Set the Index of Refraction for each layer to create realistic glass, plastic, and liquids.
• Emission Control: Make any layer emit light, using either a texture map or a solid color with adjustable strength.

Advanced Realism & Anti-Tiling

• Voronoi Rotation: An automatic anti-tiling feature that breaks up texture repetition by applying subtle, random rotations across the surface.
• Color Variation (Noise): Adds large-scale, low-frequency noise to the Base Color to break up flat colors and add a more natural, weathered look.
• Projection Blend Noise: Adds noise to the seams where the X, Y, and Z projections meet, hiding the triplanar transition lines.
• Triplanar Noise Mapping: Prevents procedural noise textures (used in masks and anti-tiling) from stretching on the sides of your model.

PBR Library & Asset Management

• Integrated PBR Library: A thumbnail grid in the UI shows materials from your chosen library folder.
• One-Click Material Application: Select a layer, click a library material, and all its PBR textures are instantly loaded.
• Multi-Library Support: Add and switch between multiple PBR library folders in the addon preferences.
• Smart Folder Import: Point the addon to a folder containing PBR texture sets, and it will automatically copy them into your active library.
• Create PBR Sets from Layers: Export any layer from your material as a brand new, reusable PBR set in your library. This allows you to build a custom library of your own procedural creations.

Baking & Export

• Intelligent Bake Operator: Converts your entire complex, procedural material into a simple, high-performance set of PBR image textures with one click.
• Automatic UV Unwrapping: The baker creates a new, optimized UV map (BMX_Bake_UVs) for the baked textures, leaving your original UVs untouched.
• Full Map Support: Bake all channels, including Base Color, Normal, Roughness, Metallic, Displacement, and Emission.
• Flexible Output: Choose your desired texture resolution and file format (PNG, JPEG, TIFF).
• Automatic New Object Creation: After baking, the addon can create a duplicate of your object with a new, simple material that already uses the baked textures, perfect for checking the result or exporting to a game engine.

  ---

🚀 Getting Started

1. Installation:
   • Download the BMixer+.py (or BMixer+paint.py) file.
   • In Blender, go to Edit > Preferences > Add-ons.
   • Click Install... and navigate to the downloaded .py file.
   • Enable "Material: BMixer+" by checking the box.
2. Accessing BMixer+:
   • Select a MESH object in your scene.
   • Open the Sidebar in the 3D Viewport (press N).
   • Find and click on the "BMixer" tab.
3. Creating Your First BMixer Material:
   • If your selected object has no material, or if its active material is not a BMixer material, the panel will display a button like "Create BMixer Material" or "Initialize BMixer." Click this button.
   • A default "Base Layer" will be automatically created.
4. Working With Layers:
   • Layer List: View and select layers.
   • Controls:
     • 👁️ (Eye Icon): Toggle layer visibility.
     • ➕ / ➖: Add / Remove layers.
     • ▲ / ▼: Reorder layers.
   • Editing: Click a layer in the list to make it active. Its properties will appear below for editing.
5. Layer Properties - Overview:
   • Name: Edit the layer's name (this also updates selective blend targets if the layer is renamed).
   • Selective Blending (for layers above base): Enable and choose which lower visible layers this one should specifically blend with.
   • Texture Maps: Assign image textures for PBR channels, use plain color, or enable emission. Adjust strengths.
   • Layer Alpha (for layers above base): Controls overall layer opacity if not in Brush Mode or if combined with Brush Mode effects.
   • Transform: Control Scale, Location (XY), and Rotation (Z) of the layer's triplanar-projected textures.
   • Face Blending: Adjust how textures from different projection axes (X, Y, Z) blend. Use "Advanced Face Blend" for per-axis control.
   • Layer Mask (Procedural - if Brush Mode is OFF): Enable and configure a procedural noise mask for blending.
   • Anti-Tiling: Enable "Voronoi Rotation" and "Color Variation."
   • Brush Mode (for layers above base): See section below.
6. Using Brush Mode:
   • Select a layer (not the base layer).
   • Check the "Brush Mode" checkbox.
     • The layer will become initially invisible (or its visibility will be solely determined by the brush mask).
   • Adjust "Brush Power" (0.0 to 1.0) to control the intensity of your painting.
   • "Paint Layer" Button:
     • Clicking this button the first time for a layer in Brush Mode will:
       1. Call bmx.setup_brush_mode: This creates a dedicated UV map (named _bmx_brush_uvs by default, or per layer) if it doesn't exist and performs a Smart UV Project. It then creates a new, black (transparent alpha) image texture (e.g., _bmx_brush_Cube_LayerName) and assigns it to the layer for painting.
       2. Call bmx.enter_brush_paint: This switches Blender to Texture Paint Mode and attempts to set the newly created brush mask image as the active paint target.
     • If already in Texture Paint mode for this layer's brush mask, clicking "Stop Painting" (the button text changes) will switch you back to Object Mode.
   • Painting:
     • Work in the 3D Viewport with shading set to Material Preview or Rendered.
     • Use Blender's standard Texture Paint tools. Paint with WHITE color to reveal the layer. Paint with BLACK to hide it again (or use the eraser).
   • "Clear Brush Mask" Button (X icon): Resets the layer's brush mask image to be fully transparent (black with zero alpha), effectively hiding the painted areas.
   • Mask Info: If a brush mask image is set up, its name will be displayed.
7. Global Settings:
   • Sync Real Time: Toggle instant material updates or use Apply Changes.
   • Advanced Engine: Switch between triplanar projection methods.
   • Projection Settings: Control normal space and triplanar mapping for noise.
   • Displacement: Set global displacement scale and midlevel. BMixer+ will attempt to set the material's Cycles displacement setting to "Displacement and Bump" if displacement maps are used, or "Bump Only" otherwise.

💡 Tips for Best Results

• Start Simple: Build up layers gradually.
• Procedural Masks (Non-Brush Mode): Experiment with Threshold and Smoothness for natural noise-based blends.
• Brush Mode Precision: Paint directly in the 3D Viewport (Material Preview/Rendered) for accurate placement. Use a low Brush Power for softer transitions.
• Selective Blending Power: This is key for advanced effects. Think about how real-world materials would interact (e.g., dust on top of specific materials, wear revealing certain underlayers).
• Anti-Tiling: Essential for large surfaces. Voronoi Rotation and Color Variation can make a huge difference.
• UV Maps for Brush Mode: BMixer+ creates a default UV map (_bmx_brush_uvs) for brush painting if one doesn't exist. For critical control, you might want to prepare your own UV layout named _bmx_brush_uvs or ensure the Smart UV Project gives a decent result for painting.
• Save Your Brush Mask Textures: The brush mask images created by BMixer+ are internal to the .blend file once packed (which BMX_OT_SetupBrushMode does). If you need to edit them externally, you'll need to unpack them first.

⚠️ Important Notes & Warnings

• Brush Mode & UVs: While the layer content is triplanar, the "Brush Mode" relies on Texture Painting, which inherently uses UV coordinates for the mask itself. BMixer+ will attempt to create a Smart UV Project named _bmx_brush_uvs if it doesn't find one, but for optimal control over where your brush strokes land, you might want to manually create/edit this UV map.
• Performance: Complex layered materials with many high-resolution textures, advanced triplanar blending, and multiple active procedural effects can be computationally intensive.
  • Use the "Sync Real Time" toggle: disable it and use "Apply Changes" for smoother editing on heavy materials.
  • Consider the resolution of your textures.
• Displacement: True geometric displacement requires sufficient mesh subdivision and is primarily a Cycles feature. Ensure your material's displacement setting (in Material Properties > Settings > Surface > Displacement) is set to "Displacement Only" or "Displacement and Bump" to see the effect. BMixer+ attempts to manage this automatically.
• Layer Renaming & Selective Blend: If you rename a layer that is being used as a target in another layer's "Selective Blend Targets" list, BMixer+ will attempt to automatically update the reference. However, it's good practice to double-check these references after renaming.
• Texture Paint Mode Context: When using "Paint Layer" for Brush Mode, ensure you are painting on the correct object and that the 3D Viewport is in "Material Preview" or "Rendered" shading mode to see the live effect of your brush strokes on the layer's visibility.
• Known Issues & Fixes:1- You have to make sure that the displacement ratios of the bottom layers are smaller than those of the top layers. otherwise there may be overlaps.2- In Selective Mixing, textures with a lot of layer difference between them can sometimes not blend. try to bring them closer together