Mesh Painter Documentation

Installation

1. Download mesh_painter.zip
2. Open Blender 4.0 or later
3. Go to Edit > Preferences > Add-ons
4. Click Install and select the downloaded zip file
5. Enable Mesh Painter in the addon list
6. The panel will appear in 3D View Sidebar > Mesh Painter tab

Overview

Mesh Painter is a Blender addon that transforms object placement into an intuitive painting workflow. Select any mesh object as a brush and paint it directly onto surfaces in real time. Whether you are populating game environments, creating architectural visualizations, or building complex scenes, Mesh Painter saves hours of manual work.

Quick Start?

Your First Paint.

1. Open a new Blender scene (Delete a cube if you must is a tradition)
2. Add a Plane  (Shift+A → Mesh → Plane) and scale it up (S, 10, Enter)
3. Add a UV Sphere (Shift+A → Mesh → UV Sphere) — this will be your brush object
4. Select the UV Sphere
5. Open the Mesh Painter panel in the sidebar
6. In the Brushes section click "Create from 'Sphere'"
7. Go to Brush Tool section and click "Start Painting"
8. Move your mouse over the plane — you will see a white circle cursor
9. Left click and drag to paint spheres onto the plane
10. Press RMB or ESC to exit paint mode

Panel Structure

The Mesh Painter panel is organized into six sections:

Brushes

The Brushes section is where you create and manage your brush library.

Creating a Brush

1. Select any mesh object in the viewport or outliner
2. In the Brushes section click "Create from '[ObjectName]'"
3. The brush appears in the Brush Library with its settings

Brush Library

Each brush in the library shows:

• Active indicator (radio button) — click to set as active brush
• Brush name — displays the source object name
• Usage count — number of times this brush has been used
• Delete button (X) — removes the brush from the library

Brush Settings

When a brush is active, its settings are displayed below it in the library.

Placement

Alignment

Randomization

Brush Tool

The Brush Tool section controls the painting experience.

Starting Paint Mode

1. Make sure you have at least one brush created
2. Click "Start Painting"
3. The header shows "●PAINT MODE"
4. Move your mouse over any surface to see the white circle cursor
5. Left click or click and drag to paint

Brush Tool Settings

Understanding Brush Radius vs Spacing

• Brush Radius controls the size of your cursor (visual only)
• Spacing (in brush settings) controls the minimum distance between placed objects in world space
• For dense painting lower the Spacing value in your brush settings
• For sparse painting increase the Spacing value

Density Guide

Exiting Paint Mode

Press RMB or ESC to exit paint mode at any time.

Precision Placer

Precision Placer allows single click placement with rotation and scale snapping for exact positioning.

Starting Precision Mode

1. Make sure you have at least one brush created
2. In the Precision Placer section click "Start Precision Place"
3. A blue crosshair cursor appears at your mouse position
4. Click once to place a single object

Snapping Controls

Snap Settings

Exiting Precision Mode

Press RMB or ESC to exit precision mode.

Erase Tool

The Erase Tool removes painted objects from your scene.

Erase Mode

1. Click "Start Erasing"
2. A red circle cursor appears
3. Left click or drag over objects to erase them
4. The painted object count updates in real time
5. Press RMB or ESC to exit erase mode

Erase Settings

Mass Erase

The Mass Erase section shows the total count of painted objects in your scene. Click "Erase All Objects" to remove every painted object at once. A confirmation dialog will appear before deletion.

Stroke Editing

Stroke Editing allows you to adjust painted objects after placement without repainting. This is one of the most powerful features of Mesh Painter.

Selection

Before editing, select the objects you want to adjust:

• Click "Select All Painted" to select every painted object in the scene
• Or manually select objects in the viewport using box select (B key)
• The panel shows how many objects are currently selected

Randomize Adjust

Randomize adds controlled variation to selected objects. Each click of Apply gives fresh results — it does not stack.

Apply — Applies randomization to selected objects
Reset — Resets all selected objects to scale 1.0 and rotation 0°

Uniform Adjust

Uniform Adjust sets every selected object to the exact same scale and rotation values.

Apply — Applies uniform values to selected objects
Reset — Resets all selected objects to scale 1.0 and rotation 0°

Stroke Editing Workflow

Paint objects → Exit paint mode → Select objects → 
Adjust sliders → Click Apply → Don't like it? Ctrl+Z → Adjust again

Setup

The Setup section configures global painting settings.

Target Object

By default Mesh Painter paints on any visible mesh surface. Setting a target object restricts painting to that object only.

1. Select a mesh object in the viewport
2. Click "Set '[ObjectName]' as Target"
3. Now painting only works on that specific object
4. Click X next to the target field to clear it

Collection Settings

When Auto Collection is enabled, painted objects are automatically organized into named collections using the format:

MeshPainter_[BrushName]_[Date]

Example: MeshPainter_Sphere_Feb11

Keyboard Shortcuts

Paint Mode

Precision Mode

Erase Mode

General

Tips & Tricks

For Game Environments

• Set a low Spacing value (0.5m) with medium Density (1.0 - 2.0) for natural coverage
• Use Randomize after painting with Rotation Z set to 360° for natural variation
• Create separate brushes for different asset types and switch between them
• Use collections to organize painted objects by area

For Architectural Visualization

• Use Precision Placer for furniture and prop placement
• Enable rotation snapping (45° or 90°) for aligned objects
• Set a Target Object to restrict painting to specific surfaces
• Use Uniform Adjust to set consistent scale for all furniture pieces

For Natural Scenes

• Paint multiple passes with different brushes for variety
• Use Randomize with Scale Variation around 20% - 40% for natural size differences
• Keep Rotation X and Y at 0° for upright objects, only randomize Z
• Combine different sized brushes for realistic distribution

Performance Tips

• Keep brush source objects low polygon count
• Use instancing (enabled by default in preferences) for large scenes
• Monitor the painted object count in the Erase Tool section
• Use collections to hide and show groups of painted objects

Troubleshooting

Objects not appearing when painting

• Check that your brush has a valid source object in the Brushes section
• Make sure your mouse is over a visible mesh surface
• Try reducing the Spacing value in brush settings
• Check the Blender console for error messages

White cursor not visible

• Make sure you have clicked "Start Painting" and are in Paint Mode
• Your mouse must be hovering over a mesh surface for the cursor to appear
• Check that the target object (if set) is visible in the viewport

Objects placing in wrong location

• Check the Offset values in brush settings are set to 0
• Make sure your source object has its origin set correctly
• Try applying scale and rotation to your source object (Ctrl+A in viewport)

Erase mode not detecting objects

• Make sure objects are inside a MeshPainter collection
• Objects must have been painted using Mesh Painter to be detected
• Try increasing the Erase Radius value

Performance slowing down

• Reduce the number of objects using Erase Tool
• Enable instancing in addon preferences
• Hide collections you are not currently working on

Changelog

Version 1.0.0 (Feb 2026)

• Initial release
• Paint mode with real time cursor feedback
• Precision placement mode with Ctrl and Shift snapping
• Erase mode with adjustable radius and mass erase
• Brush system with unlimited brushes and full settings
• Post paint stroke editing with Randomize and Uniform Adjust
• Smart collection management with automatic naming
• Surface normal alignment
• Full randomization control per axis
• Undo and redo support

Support

For bug reports, feature requests and support contact me, don't hesitate to inbox.
[email protected]

Mesh Painter by Egret — Keep creating beauty in the world! Forza Michelangelo.