Overview

PaintForge turns any mesh into a paintable surface at runtime. Everything is driven by a single Actor Component plus a small family of UMG widgets.

Quick Start

Get a paintable character on screen in a few minutes.

Default controls

Requirements

A short checklist to make sure painting, sampling and the UI all work in your project.

Enable “Support UV From Hit Results”

Open Edit → Project Settings → Engine → Physics, tick Support UV From Hit Results, then restart the editor. (Equivalent config line, for reference:)

Automatic vs Manual Setup

PaintForge can run completely hands‑off, or you can take control of every piece. Both routes use the same component.

Automatic (recommended to start)

Leave the component’s auto toggles on (they all default to ON) and everything is created for you when the game begins — no graph wiring at all:

Manual (full control)

Turn the matching toggle OFF and do that part yourself from Blueprint. You can mix and match — e.g. keep auto input but create the widget manually.

Material Setup

PaintForge writes the paint into a texture (or vertex colors) and feeds it to your material through named parameters.

For the standard texture path, the mesh material needs two Texture Parameters. The painted base color goes into the first, and a packed metallic/roughness map (R = metallic, G = roughness) into the second:

These names are configurable in Project Settings → PaintForge. The simplest route is to start from the bundled M_Paintable material and apply it (or a child instance) to your mesh.

Overlay (keep original textures)

To paint on top of a textured mesh instead of replacing its look, enable Preserve Original Texture. Paint then accumulates in a transparent layer composited over the original through the overlay material (M_PaintableOverlay), which exposes:

Vertex‑color path

For characters with mirrored or overlapping UVs, enable Use Vertex Color and assign a material that reads the Vertex Color node (RGB → base color, A → metallic), e.g. the bundled vertex material. No UV unwrap required.

Painting Modes

Pick the path that matches your asset. All three are just toggles on the component.

Plugin Classes

Everything PaintForge gives you, by its in‑editor name. Components are added via Add Component; widgets are created as Widget Blueprints or spawned for you.

Components

Widgets

Stateless color/brush helper nodes also live in the Function Library.

Paintable Component

“PaintForge Paintable” — the heart of the plugin: drop it on an actor to make one of its meshes paintable.

Key setup properties

Lifecycle

With Auto Initialize on, the component prepares everything it needs when the game begins — no setup required. To control it yourself, turn the toggle off and use these Blueprint nodes on the component:

Painting World Objects

“PaintForge Object Paintable” — a streamlined variant for props and level geometry.

Use the regular Paintable component on your player/character (it owns the brush, input, camera and UI), and drop the lighter Object Paintable component on static meshes and props you want the player to be able to paint. It hides the brush / input / UI / camera categories because the player’s component drives those.

To let the player’s brush reach those props, set the player component’s Target Mode to Character + World Objects or World Objects Only.

The Brush

The Paint Forge Brush is the single structure that describes what to paint. The component holds an Active Brush and exposes a setter node for every field.

Brush shapes

Soft CircleHard CircleSoft SquareHard SquarePixel CirclePixel SquareDiamondCrossHorizontal LineVertical Line

Setting the brush from Blueprint

The component exposes one node per brush field, so you can drive the brush from any Blueprint event:

Set Brush ColorSet Brush MetallicSet Brush RoughnessSet Brush OpacitySet Brush HardnessSet Brush ShapeSet Brush SizeAdjust Brush Size

Brush size is clamped between Min Brush Size and Max Brush Size; Brush Size Step controls how much each up/down input changes it.

Target Modes

Target Mode decides which surfaces the brush is allowed to touch.

3D Eyedropper

“PaintForge Eyedropper” — the “3D Spoit”. Samples the real color you see in the world, plus metallic/roughness from the hit surface.

The component auto‑creates an eyedropper when the game begins (Auto Create Eyedropper) and attaches it to the camera. Color is read from the rendered scene pixel under the aim point — so multi‑material objects (e.g. a painting) just work, on PC and mobile. Metallic / Roughness are read from the surface material via a post‑process capture or runtime scalar parameters.

Using it

On the component, use Toggle Eyedropper to arm/disarm sampling (same as holding Space) and Is Eyedropper Active to check the state. The eyedropper itself also offers direct sampling nodes:

Each returns a Paint Forge Sample with Color, Metallic, Roughness, Has Material Props and Valid. Feed it into a paint panel with the panel’s Apply Sample node and the brush updates live.

Camera & Cursor

While the paint panel is open, PaintForge can take over the camera and show a surface‑hugging 3D brush cursor.

Camera

With Control Camera In Paint Mode on, Alt+drag orbits and the wheel zooms while painting. Tune it with Min/Max Arm Length, Zoom Step, Orbit Sensitivity, Paint Camera Orbit Speed and the pitch clamps. The spring arm is auto‑resolved from the owner, or set Camera Boom directly.

3D ring cursor

With Enable Brush Cursor on, two surface‑tangent rings preview the brush footprint on the mesh. Every aspect is styleable: Ring1/Ring2 Color, Thickness, Scale Mul, Ring Brightness, Surface Offset and Cursor Min Radius. You can also assign 2D cursor icons (Brush Cursor Icon, Eyedropper Cursor Icon) used as a custom mouse cursor while the panel is open.

Controls & Input

PaintForge is built on Enhanced Input, with sensible default keys so it works the moment you press Play.

When the game begins (with Auto Setup Input on) the component adds its Default Mapping Context and binds these actions. Assign your own Input Actions to remap, or leave them empty to use the built‑in fallbacks:

Turn off Bind Default Keys When No Action for a pure Input‑Action setup with no built‑in key fallbacks. If you set up input on your pawn manually, the component also provides a Bind Paint Input node you can call from your pawn’s input setup.

Creating & Binding Widgets

Two ways to get a paint UI on screen: let the component build it, or design and wire your own.

Option A — Let the component do it

Keep Auto Create Paint Widget on (and assign Paint Widget Class if you made a custom design). The component spawns the widget, adds it to the viewport and binds it to itself automatically. Nothing else to do.

Option B — Create & bind it yourself

Turn Auto Create Paint Widget off and do it from your own Blueprint:

Classic Paint Panel

“PaintForge Widget” — a complete, ready‑to‑use paint panel.

With Auto Create Paint Widget on, the component spawns this panel for the local player automatically (hidden until you press Tab, if Start UI Hidden is set). It shows the color picker, a brush‑shape cycler and metallic/roughness fields, and previews the brush size with a ring.

To drive a panel yourself, use its Blueprint nodes: Set Target Component to bind it to a paintable, Set Brush / Get Brush to read or write the brush, and Apply Sample to push an eyedropper result in. The On Brush Changed event fires whenever the user edits the brush.

To swap in your own design, set Paint Widget Class to a Widget Blueprint created from PaintForge Widget. Optional on‑screen movement / camera sticks can be enabled on the widget itself for touch builds.

Designable Palette

“PaintForge Palette” — a fully designable, professional color palette.

Every control is optional: design your own layout in a Widget Blueprint, include only the controls you want and name them per the table below, and the palette wires them all to the component and keeps RGB / HSV / Hex / color wheel / sliders synchronized live in both directions. Used directly with no design work, it builds a complete panel automatically.

Set the component’s Palette Paint Widget Class to use it instead of the classic panel.

Recognized element names

UI Building Blocks

Self‑contained, reusable widgets you can drop into any layout. The palette auto‑discovers and wires them.

Brush Slider

The PaintForge Brush Slider is one configurable control: a label plus a spin box (drag or type) bound to a single property you choose from a dropdown — Size · Metallic · Roughness · Opacity · Hardness. Drop several, set the Property on each, and the palette auto‑wires them — no widget naming needed. Fully styleable (label, font, accent, decimals) and Blueprint‑subclassable.

HUD Button

“PaintForge HUD Button” — a self‑contained action button: drop it anywhere, pick its job, done.

Choose the command from the Action dropdown and it just works — no naming, no graph, no wiring. The paintable component is resolved automatically from the owning player’s pawn (or point it at a specific one with SetTargetComponent).

Style via Button Height, Accent Color, Label Color and an optional custom font, or subclass in Blueprint to redesign the look.

Joysticks & Camera Sticks

“PaintForge Virtual Joystick” and its camera‑tuned variant “PaintForge Camera Stick” — reusable on‑screen sticks for touch (and mouse) control.

A fixed outer ring with a draggable knob that emits a normalized 2D axis through OnAxisChanged and springs back on release. Built from standard UMG, so it runs identically in the editor, packaged desktop and on a real device — handling both touch and mouse. It knows nothing about gameplay: bind OnAxisChanged to whatever you want to drive.

Touch & Mobile

Flip one switch and PaintForge runs a complete touch flow with its own HUD.

Turn on Mobile Mode. When the game begins the component spawns a touch HUD (the PaintForge Mobile HUD), disables the 3D ring cursor and skips the raw mouse/key bindings so nothing fights the HUD. The desktop path is completely untouched when this is off.

Gestures

The HUD auto‑builds its buttons and optional left/right virtual sticks, or you can inherit it as a WBP and supply your own controls by name (all BindWidgetOptional). Tunables include Mobile Paint Resolution, Mobile Orbit Sensitivity and Mobile Pinch Sensitivity.

For custom flows, the mobile entry points are all available as Blueprint nodes on the component:

Mobile Begin StrokeMobile Paint AtMobile End StrokeMobile OrbitMobile Pinch ZoomMobile Sample AtSet Mobile Eyedrop ArmedMobile UndoMobile FillMobile Clear

Project Settings

Project‑wide defaults live under Project Settings → Plugins → PaintForge.

Function Library

A set of ready‑made Blueprint helper nodes for color and brushes, available in any graph.

Online Multiplayer / Replication

PaintForge supports server-authoritative runtime painting for replicated actors. Paint, Fill and Clear actions can be synchronized across connected clients without replicating render-texture pixels every frame.

Project setup

Network actions

Blueprint API Cheat‑Sheet

The most useful component calls, grouped by what you’re doing.

Events you can bind

On PaintedOn Toggle UIOn Eyedrop StartOn Eyedrop Stop — on the component; On Brush Changed on the widgets.

Troubleshooting

Nothing happens when I paint

Check the mesh material exposes the PF_BaseColor / PF_Material texture parameters (or use M_Paintable), and that the component is initialized. In packaged builds enable Allow CPU Access on skeletal meshes.

Paint bleeds to the back of thin limbs

Raise Facing Threshold so only front‑facing texels accept paint.

The camera fights my own controls

Skip your pawn’s free‑look while IsPaintUIVisible() is true, or route look input through HandleLookInput().

Only part of my character paints

Keep Paint All Material Slots on, or for mirrored/overlapping UVs switch to the vertex‑color path.

Mobile HUD doesn’t paint

Make sure Mobile Mode is on; the full‑screen paint surface only activates while the palette is open.