Magic Vertex Painter 5.0.0 - Documentation & FAQ

1. Introduction

Magic Vertex Painter is a comprehensive Blender addon designed to streamline the workflow for game developers and environment artists. It provides a powerful and intuitive toolset for scattering assets like grass, rocks, and flowers across a mesh using vertex painting. The addon combines geometry nodes for procedural distribution with a flexible shader system for detailed texturing and color control, all managed through a single user-friendly panel.

Key Features:

• Paint up to 10 different asset channels (C0-C9) on a single object.

• Procedurally control asset density, scale, rotation, and distribution.

• Advanced ground material shader with customizable procedural textures (Noise, Voronoi, Wave, Brick).

• Per-asset controls for wind animation, vertical alignment, and texture influence.

• Use texture masks for both the overall ground and individual asset channels.

• Tools for converting scattered instances into real mesh geometry.

• Utility operators for baking textures, separating meshes by material, and cleaning geometry.

2. Installation

1. Open Blender version 4.5.0 or newer.

2. Go to Edit > Preferences.

3. Navigate to the Add-ons tab.

4. Click the Install... button, then find and select the addon package you downloaded. The file is typically named Magic Vertex Painter.zip.

5. After installing, find "Magic Vertex Painter" in the list and enable it by checking the box next to its name.

6. Once enabled, the addon panel will appear in the 3D Viewport's sidebar. You can access it by pressing the N key and looking for the "Magic Painter" tab.

3. Main UI Panel Overview

The entire functionality of the addon is controlled from the "Magic Painter" panel in the 3D View's UI sidebar.

3.1. Asset Management

These buttons at the top of the panel are for managing and importing asset collections.

• Assets Model: Opens a file browser to import models from the addon's asset/Assets Model folder. These are typically pre-made assets that can be used with the system.

• Other Model: Opens a file browser to import models from the addon's asset/Other Model folder. Use this for importing supplementary models like props or background elements.

• Trash Icon (Clean All Data): A powerful cleanup tool. This operator removes all objects, materials, collections, and node groups generated by the addon from your scene. It effectively resets the addon's presence in the file.

3.2. Global Shader & System Controls

This row of controls manages the overall look of the ground material and the asset system.

• Ground Color: When enabled, the addon applies its procedural ground shader to the object you are painting on. Disabling this can be useful if you are using an existing material and only want to use the asset scattering feature.

• Plant Shadow: This toggle controls the color blending on the ground material. When enabled, the areas where you paint assets will also color the ground beneath them, creating a "shadow" or color bleed effect.

• Texture Icon (Ground Texture Mask): This button allows you to select a texture to mask the entire procedural ground material. You can use this to create paths, patches of dirt, or other variations. The button's pressed state indicates if a mask is active.

• Main Model: When enabled, this automatically imports the 10 default assets (Grass, Rock, Flower, etc.) from the addon's asset library and assigns them to their corresponding C0-C9 channels. This is a quick way to get started.

• Unwrap UV: A simple utility that performs a basic UV unwrap on the currently selected object.

3.3. Core Painting Workflow

This is the main section for starting, continuing, and ending a painting session.

• Create New / New Object: This starts a new painting session by creating a new object from the addon's library of base meshes (e.g., a plane, sphere). It automatically sets up the entire system on this new object and enters Vertex Paint mode.

• Selected Object / Paint Object: This applies the Magic Vertex Painter system to your currently selected mesh object. It adds the necessary vertex color attributes, the geometry nodes modifier, and modifies the material, then enters Vertex Paint mode.

• End Painting: Appears during an active painting session. This safely exits Vertex Paint mode, finalizes the session, and restores the visibility of other objects in the scene.

• Continue Paint: Appears if you have an active session but have switched out of Vertex Paint mode. Click this to jump back to painting on the correct object.

3.4. Brush Controls

• Draw / Eraser / Blur: These three toggle buttons switch between the primary painting functions.

  • Draw: Uses a white brush color to add assets.

  • Eraser: Uses a black brush color to remove assets.

  • Blur: Uses the Blur brush to soften the transitions between painted areas.

3.5. Active Channel Instance Settings

These settings apply to the currently selected asset channel (C0-C9).

• Density: Controls how many instances are scattered in the painted area. Higher values mean more instances.

• Seed: Changes the random pattern of the distribution.

• Min Scale / Max Scale: Sets the minimum and maximum random size for the instances.

• Rotate: Applies a manual rotation offset to all instances in that channel.

• Vertical Growth: A slider that controls the alignment of the instances.

  • 0.0: Instances will follow the surface normal of the ground mesh.

  • 1.0: Instances will point straight up along the world's Z-axis, regardless of the ground's angle.

  • Values in between will blend these two alignments.

3.6. Ground & Asset Texture Settings

This section allows for deep customization of the procedural textures used by the addon's shader.

• Ground [Texture Type] Settings: This expandable section controls the main procedural ground texture.

  • Dropdown (Noise/Voronoi/Wave/Brick): Selects the base procedural texture type for the ground.

  • Texture Properties: Below the dropdown, settings specific to the chosen texture will appear (e.g., Scale, Detail, Roughness for Noise; Mortar Size, Brick Width for Brick). You can adjust these in real-time.

  • Mapping: An expandable sub-section to control the texture's mapping (Location, Rotation, Scale).

• Asset [Texture Type] Settings: This expandable section controls the procedural texture used for the "Plant Shadow" effect of the currently active asset channel.

  • The controls are identical to the Ground Texture Settings but affect only the selected channel's texture.

3.7. Bump & Mix Settings

• Strength / Distance (Top Row): Controls the master bump effect for the procedural ground texture.

• [Channel] Strength / [Channel] Distance (Second Row): Controls the bump effect for the active asset channel's procedural texture.

• Mix Button (Template/Mix/Noise): This button cycles the Mix Factor between three main states: 1.0 (Template/Solid Color), 0.5 (Mix), and 0.0 (Procedural Texture).

• Factor Slider: A slider to manually control the blend between the procedural texture (0.0) and the solid instance color (1.0) for the active channel's "Plant Shadow".

3.8. Post-Painting Utilities

These operators are used after you have finished painting and ended the session.

• Convert to Mesh: Applies the geometry nodes modifier, converting all the scattered instances into real, editable mesh geometry. This is a destructive operation and cannot be undone easily.

• Separate: (Available after converting to mesh) Separates the combined mesh into individual objects based on their material. It will then intelligently rejoin parts that belong to the same original asset.

• Bake PNG: Opens a powerful baking tool to bake the complex procedural material down to simple PBR image textures (Base Color, Normal). It has several modes:

  • Bake PNG and Export FBX for UE5: Bakes textures and exports a game-ready FBX for Unreal Engine.

  • Bake all Material to one image (Keep UVs): Bakes all materials on an object to a single texture set, using the object's existing UV map.

  • Bake all material to one image (Auto Smart UV): Creates a new UV map using Smart UV Project and then bakes all materials to one texture set.

  • Bake Atlas (Multiple Objects & Auto Smart UV): Creates a single texture atlas for multiple selected objects, unwrapping them all together and baking their materials to one texture set.

3.9. Color Ramps

When a painting session is active, color ramp widgets will appear, allowing for artistic control over the ground and asset colors.

• Ground Color Ramp: Controls the color gradient for the main procedural ground texture.

• [Channel] Plant Shadow Color Ramp: Controls the color gradient for the active asset channel's procedural texture.

3.10. Asset Channels (C0 - C9)

This is the heart of the addon, where you manage each of the 10 distributable asset layers. Each row corresponds to one layer.

• C0 - C9 Button: Clicks to select the active channel for painting and for editing in the "Active Channel Instance Settings" panel above. A pressed-down appearance indicates the active channel.

• Object Picker (Mesh Icon): Assigns a mesh object from your scene to be scattered for this channel. Click to select an object.

• Color Picker: Sets the solid color for this channel. This color is used for the "Plant Shadow" effect and can be blended with the procedural asset texture using the Mix Factor slider.

• Texture Icon (Per-Channel Mask): Assigns a unique texture mask to this specific channel. This allows you to paint an asset broadly, but have a texture control its final placement (e.g., using a noise texture to break up the pattern). The button is depressed when a mask is active.

• Wind Icon (Toggle Wind): Enables or disables a procedural wind animation effect for this channel. When enabled, the Rotate settings in the "Active Channel Instance Settings" panel are replaced with Wind 1 and Wind 2 speed controls.

Magic Vertex Painter - Frequently Asked Questions (FAQ)

Painting

Q: How do I start painting on an object? A: There are two main ways:

1. For a New Object: Click the "New Object" button. The addon will automatically create a pre-configured plane and immediately enter Vertex Paint mode, so you can start painting right away.

2. For an Existing Object: Select your own model in the scene, then click the "Paint Object" button. The addon will automatically set everything up on your model and enter Vertex Paint mode.

Q: I've painted grass, and now I want to paint rocks. How do I switch between them? A: In the asset channel list at the bottom of the panel (C0-C9), each channel represents an asset. By default, C0 is grass and C1 is rock. To paint rocks, simply click the C1 button. It will become depressed, indicating it's the active channel, and your brush will now paint rocks. To switch back to grass, click the C0 button.

Q: How do I erase assets that I have already painted? A: In the brush control section of the panel, click the "Eraser" button. Your brush will now be in erase mode. Paint over the areas where you want to remove assets. When you are done, click the "Draw" button to switch back to the normal painting mode.

Q: What is the difference between the "Draw," "Eraser," and "Blur" brush modes? A:

• Draw: This is the primary mode for adding assets. The brush increases the vertex color value (making it brighter), which generates the assets.

• Eraser: This is the removal mode. The brush decreases the vertex color value (making it darker), which removes the assets.

• Blur: This is used for smoothing transitions. Painting on the borders between different asset areas will blend them more naturally, avoiding hard edges.

Wind Effect

Q: How do I add a wind-swaying effect to my grass? A: In the row for the asset channel you want to animate (e.g., C0 for grass), click the Wind Icon at the end of the row. After clicking it, the instances for that channel will begin to sway when the animation is played.

Q: Can I have wind on my grass but not on my rocks? A: Yes. The wind effect is controlled independently for each asset channel. You only need to click the wind icon on the grass channel (e.g., C0) and leave it disabled on the rock channel (e.g., C1).

Q: How do I control the wind's strength and speed? A: When you enable the wind effect for a channel (by clicking the wind icon), the "Rotate" setting in the panel above will be automatically replaced by two sliders: "Wind 1" and "Wind 2". By adjusting these values, you can change the speed and complexity of the wind's motion.

Q: I enabled the wind, but nothing is moving. Why? A: The wind effect is tied to Blender's timeline. You will only see the animation if the timeline is playing. After enabling the wind, you must play the animation (press the Spacebar) to see the effect. The assets will not move on a static frame.

Baking & Exporting

Q: What is "baking" and why do I need it? A: Baking is the process of converting a complex, procedural material (generated by nodes) into simple image textures (like a .PNG file). You need to bake your model for several reasons:

• Exporting to Game Engines: Game engines like Unreal Engine and Unity cannot read Blender's procedural node materials. You must bake them into textures first.

• Performance: A baked model uses simple image textures, which results in much faster rendering and viewport performance.

• Finalizing the Look: It locks in the appearance of your model when you no longer need to make procedural adjustments.

Q: What is the correct workflow for baking my model? A:

1. First, ensure you have finished all your painting and have clicked the "End Painting" button.

2. Click the "Convert to Mesh" button. This is a critical step that turns all the procedurally generated instances into real, editable geometry.

3. Select the object you want to bake in the 3D viewport.

4. Click the "Bake PNG" button.

5. In the pop-up window, choose a baking mode (e.g., "Bake PNG and Export FBX for UE5"), set your desired texture resolution, and begin the bake.

Q: What are the differences between the baking modes? A:

• Bake... (Keep UVs): Bakes using the object's existing UV map. Use this option if you have already manually unwrapped your model.

• Bake... (Auto Smart UV): The addon will automatically create a new "Smart UV" map for your model before it bakes. This is useful for quick results when you don't have a pre-made UV map.

• Bake Atlas...: This mode creates a single, shared UV map and texture set for multiple selected objects. It is excellent for optimizing game assets by reducing draw calls.

• Bake PNG and Export FBX for UE5: A fully automated workflow designed for game development. It bakes the Base Color and Normal maps and exports an FBX file that is ready to be imported directly into Unreal Engine 5.

Q: The "Bake PNG" button is grayed out and I can't click it. What's wrong? A: This operator requires you to have at least one mesh object selected in the 3D viewport. Simply left-click on the model you wish to bake, and the button will become active.

Magic Vertex Painter - FAQ (Extended Edition)

Advanced Techniques & Customization

Q: Can I use my own ground material instead of the addon's procedural one? A: Yes. Before you start painting, uncheck the "Ground Color" box. Then, select your object with its custom material and click "Paint Object". The addon will apply its instance scattering system but will attempt to inject the necessary shading logic into your existing material instead of completely replacing it. You can then fine-tune the result in the Shader Editor.

Q: How do the per-channel texture masks work with my brush strokes? A: They work in a multiplicative way. The final density of the asset is the product of your painted vertex color intensity (the area you painted) and the brightness of the texture mask (the white areas of the texture). This means assets will only appear in areas where you have both painted with your brush and where the mask texture is also bright. This is perfect for creating random patches or complex patterns.

Q: How do I edit the Color Ramps for the ground or assets? A: When you are in an active painting session (i.e., after clicking "New Object" or "Paint Object"), the Color Ramp editors will appear at the bottom of the addon panel.

• "Ground Color Ramp": Controls the color of the main procedural ground material.

• "[Channel] Plant Shadow Color Ramp": Controls the color of the "Plant Shadow" effect for the currently selected channel. You can add, delete, or modify the color stops here directly, just as you would in the Shader Editor.

Q: Can I modify the Geometry Nodes tree myself for more complex effects? A: Absolutely. The "Geo_Grass" modifier created by the addon is a standard Geometry Nodes setup. You can switch to the Geometry Nodes Editor at any time to modify the node tree. For example, you could add more complex wind logic, or use the mesh's position or slope to influence the scale of the assets.

Q: How can I change the default assets that are loaded with the "Main Model" preset? A: The addon's default assets are stored as individual .blend files in its installation directory, inside the asset/Main Model/ folder (e.g., Grass.blend, Rock.blend). You can customize your preset library by replacing these files. Just ensure that the object name inside your custom .blend file matches the original object's name (e.g., the object inside Rock.blend should be named Rock).

Tools & Utilities

Q: What exactly does the 'Separate' tool do? A: This tool is very useful after you have used "Convert to Mesh". Its function is a two-step process:

1. First, it separates your complex, combined mesh into multiple independent objects based on their material assignments.

2. Then, it automatically identifies and re-joins the parts that originally belonged to the same asset (for example, a tree model with separate materials for the trunk and leaves would be rejoined into a single, complete tree object). This is very convenient for organizing and managing your assets after baking.

Q: When should I use the "Auto Clean Mesh" tool? A: You should use this tool after performing heavy mesh operations, such as after using "Convert to Mesh" or importing a complex model that might have messy geometry. It automatically runs "Merge by Distance" to weld close vertices and "Delete Loose" to remove stray points or edges, helping you quickly clean and optimize your models.

Q: How do I completely remove all data created by the addon in my file? A: Click the Trash Can Icon (Clean All Data) at the top of the panel. This comprehensive cleanup action will:

• Delete all objects with the "Geo_Grass" modifier.

• Delete the "Ground_Grass_System" material and all related Geometry Node groups created by the addon.

• Delete the asset collections imported by the addon (e.g., "Main Model", "Assets Model"). This is a thorough reset, so use it with caution.

Troubleshooting

Q: The custom assets I'm using have the wrong size; they are either too big or too small. A: Check two things:

1. Original Object's Scale: Make sure the original mesh you are using as an instance has its scale applied. Select it in the viewport, press Ctrl+A, and choose "Scale".

2. Addon's Scale Settings: Check the "Min Scale" and "Max Scale" sliders for the current channel in the addon panel and ensure their values are appropriate.

Q: Why can't I have more than 10 asset channels (C0-C9)? A: This is the current design limit of the addon. The core systems, including the vertex color attributes, shader nodes, and UI, are built around these 10 channels. It is not possible to add more channels through the user interface.

Q: My object's original material disappeared after I used "Paint Object". What can I do? A: This happens when you use "Paint Object" on a model that has no material assigned; the addon will create a new "Ground_Grass_System" material for it. If you want to keep your original material, make sure it is assigned to the object before you start the process, and also uncheck the "Ground Color" option in the panel. This will tell the addon to inject its nodes into your material instead of replacing it entirely.

Q: The addon is showing errors or not working correctly after I updated Blender. A: Addons are developed for specific versions of Blender (this one is for 4.5.0). When Blender has a major update, API changes can break older addons. Check the addon's product page or contact the author to see if an updated version compatible with the new Blender release is available. Re-downloading and reinstalling the latest version of the addon usually solves the problem.

Contact

If you have any questions, suggestions, or feedback about Magic Vertex Painter, please contact Onion365:

• Email: [email protected]

• Private Message: Contact me via the SuperHiveMarket platform.