Ucupaint: a texture layer stack for Blender that treats painting as compositing

A texture layer stack rather than a single image

Blender's stock material workflow paints into one texture. Ucupaint replaces that with a stack: fill layers, overlay layers, modifiers and masks, each with its own blend mode and opacity, composited down into the texture the material samples. The description says the add-on manages texture layers for the Eevee and Cycles renderers, and the repository layout backs that up rather than contradicting it. `Layer.py`, `layer_common.py` and `transition.py` handle the stack, while `Modifier.py`, `Mask.py` and `MaskModifier.py` are the non-destructive operators that sit above it.

The layer list in `transition_common.py` and `layer_common.py` is effectively the data model, and reading those two files is the fastest way to understand what a layer can be. The presence of `NodeEditor` integration in the menu locations confirms the add-on builds real shader nodes rather than compositing externally in image space.

The practical difference is that a layer stack is non-destructive in the way a Photoshop document is. A fill layer with a gradient can sit under an overlay that holds grime, and neither has to be flattened into a baked PNG to be edited later. That is the entire value proposition, and it is why the modifier classes exist as operators rather than as one-shot image operations.

Installing for old and new Blender alike

There are two installation paths and they are not interchangeable. The release path is the traditional one: go to the releases page, download the zip matching your Blender version, then install it through Edit > Preferences > Add-ons.

Edit > Preferences > Add-ons

That step is not in the README as code, but the sequence it describes is: press Install, browse to the downloaded zip, and confirm. The second path is the Blender Extension Platform, which works for Blender 4.2 and newer.

Edit > Preferences > Get Extensions

You search for Ucupaint there and install it like any other extension. The README flags one real difference between the paths: the extension platform version has no branch selection. If you have been using branch selection to test unreleased features, that capability is specific to the release-zip route.

Note what the release numbering means. Recent tags are `2.4.9`, `2.4.8` and `2.4.7`, so a patch release is a patch of the add-on's own version, not of Blender. The add-on version and the Blender version are separate axes, which is why the compatibility claim spanning 2.76 onward needs several release zips rather than one.

Where the interface lives across eight years of Blender

The README gives two menu locations because Blender moved its sidebar between those versions.

On Blender 2.7x the entry is in View 3D > Tool Shelf > Ucupaint. From Blender 2.80 onward it moves to the Sidebar, reachable from either View 3D or the Node Editor. The reason for offering it in the node editor is that this add-on's work happens in shader nodes, and being one click away from the node graph is most of the convenience.

Compatibility is stated as all official Blender versions from 2.76, with some features reserved for more recent releases. That claim is broad enough that the repository layout deserves attention. Three blend library files sit at the root: `lib.blend`, `lib_281.blend` and `lib_282.blend`. Those are per-version node libraries checked into the repository, and their existence is the concrete evidence behind the compatibility claim. Blender's node system changed shape around 2.81 and 2.82, and shipping separate library files per era is how the add-on keeps its node groups loading across that boundary.

So the honest reading is: the add-on loads everywhere from 2.76 up, and the node library it depends on is versioned per Blender era. If you are on a very old Blender and a feature is missing, that is the documented carve-out rather than a bug.

Baking, decals and the modules that back the layers

A layer stack is only useful if you can collapse it when the renderer needs a single texture, and that is what the baking layer handles. `Bake.py`, `BakeInfo.py`, `BakeTarget.py` and `BakeToLayer.py` are four separate modules for one operation, which tells you the bake path is not a single code path. Bake targets can differ, and baking into a layer rather than into a texture file is a separate target type again.

The decal system is `Decal.py`, and it sits on top of the mask system rather than replacing it. `UDIM.py` and `ImageAtlas.py` cover the two tiling schemes a paintable surface might use: UDIM tiles for multi-image character sets, and an atlas packed into a single image. `vector_displacement.py` and `NormalMapModifier.py` handle the derived data that a material needs beyond color.

What that module list implies for a user is that Ucupaint is trying to cover the same ground as a dedicated texture painting application, not just add a couple of layers. Every one of those modules is a place where a bug report will eventually land, and the presence of `tests/` and a `Test.py` at the root says the author treats that as a real surface.

The addon_updater bridge and what it implies

Three files handle updating: `addon_updater.py`, `addon_updater_ops.py` and `addon_updater_preferences.py`. Splitting the concern that way, with a preferences module of its own, is the shape of a vendored dependency rather than a hand-rolled download, and it is worth knowing that an updater of this kind is fetching and installing a zip on the user's machine.

Its presence interacts directly with the extension platform path described earlier. A user who installs from the releases page gets the updater's behavior, which is version-specific and branch-aware. A user who installs from the Blender extension platform gets whatever the platform's own update mechanism does, and the README's note that this version has no branch selection is really a note about which update story you are in. Two installation routes, two update models, one add-on.

`blender_manifest.toml` exists for the extension platform build, and `preferences.py` holds the add-on's own settings. Between them, a user on either path has somewhere to configure the add-on, and a developer reading the tree can tell which parts exist to satisfy Blender 4.2 plus versus which parts have been there since the 2.7x era.

Where the documentation actually lives

The README is short and points outward for everything substantive. Documentation and demos live in a separate wiki repository at `ucupumar/ucupaint-wiki`, published at the project's GitHub Pages site, and the README is candid that it is not finished.

The Discord server is offered as the support channel, and the wiki repository accepts contributions, which means the documentation is maintained separately from the code by the same person. That is a reasonable arrangement for a solo-maintained Blender add-on, but it means the release zip is where you get reference material and the wiki is where you get explanation.

Two details in the tree are worth a reader's attention. `credits_ui.py` suggests in-addon attribution, which is common for texture artists who license brush sets. `Localization.py` means the interface is translatable, which for a tool used by artists across regions is more than a nicety. Neither is documented in the README, and both are the kind of thing that only becomes visible when you read the repository.

Editorial conclusion

Ucupaint is a serious piece of tooling rather than a convenience wrapper, and the version span it covers is the most interesting fact about it. One add-on supports Blender from 2.76 through the current extension platform releases, which means the node library files and the addon_updater shim exist to bridge roughly eight years of Blender API churn. Start with the releases page to match your Blender version, read the wiki for the layer model, and expect the real documentation to live outside the repository.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. README
4. Releases
5. ucupumar/ucupaint on GitHub