Ultimate Colorizer

This guide leads with the no-code workflow, then covers the recolor engine, the runtime systems, and the scripting API and reference at the end.

⤓ Installation

Import once — there is nothing to configure to start recoloring.

Requirements

• Unity 6000.0 or newer (Unity 6).
• Render pipeline: Built-in and URP are supported and verified. HDRP is supported through pipeline-aware material adapters (verify on an HDRP project before shipping an HDRP claim).
• Works with both the Input System package and the legacy Input Manager — no special input package is required.
• No third-party dependencies. Source-available C#.

What gets installed

Assets/UltimateColorizer/
  Runtime/        // Core model, texture/material/mesh engines, palettes,
                  //   runtime customization, characters, batch, SDK, validation
  Editor/         // Recolor Studio, windows, no-code inspectors, Welcome,
                  //   GameObject scaffolding, headless validation/build runners
  Demo/           // An interactive scene showcasing every feature
  Documentation/  // You are here
  Samples/        // Texture, material, mesh, character, cosmetics sample scenes
  Tests/          // EditMode + PlayMode (run headless via Unity -runTests)Project

⚡ Quick Start (No-Code)

Recolor a real object in the scene without writing a line of code.

🔧 Editor Tools & No-Code

Every primary capability is reachable by clicking — add a component, assign data, pick options, get a result.

The four entry points

Live preview in the Inspector

The custom inspectors wrap their fields in change-tracking: when you edit a color, texture or option, the component re-applies and the Scene view repaints — so you see the result as you edit, before pressing Play. Property fields that reference a material (color/texture property names) become dropdowns populated from the assigned renderer's shader, so you pick valid options instead of typing strings.

🧩 Recolor Components

Add these from Add Component → Ultimate Colorizer (or via the GameObject menu).

➕ GameObject Menu

One click drops a ready, pre-wired object into the scene (full Undo, auto-selected).

🎨 Palettes & Import

Palette assets hold named, role-tagged colors and import/export as JSON.

Create a palette

Assets → Create → Ultimate Colorizer → Palette. The palette inspector shows a swatch strip, a one-line summary, and Import JSON / Export JSON buttons.

Harmony generation

Generate palettes from a base color with PaletteGenerator.Generate(seed, mode, count). Modes include Complementary, Analogous, Triadic, Monochrome, Value Ramp, Split-Complementary, Tetradic, Saturation Ramp, Warm and Cool. The Palette Browser exposes this visually.

⚙ How It Works

A profile describes what to recolor; processors do the work; a service routes them.

1. A RecolorProfile (ScriptableObject) holds targets, palettes, regions, operations and runtime channels.
2. Each RecolorTarget names a source (texture, material, mesh, sprite, tilemap, renderer, character) and a RecolorTargetType.
3. An IRecolorProcessor self-selects per target (texture/material/mesh/tilemap) and applies the profile's operations.
4. RecolorProcessingService routes a target to the right processor through a RecolorProcessorRegistry and returns a RecolorResult with generated objects and validation issues.

🖼 Textures & Sprites

CPU texture recoloring with deterministic, non-destructive output.

• Replace color with tolerance and a choice of color-distance metric (RGB, weighted RGB, CIE76 approximation).
• Palette remap from a source palette to a target palette.
• Masks — threshold, channel, UV-rect, dilate/erode, combine.
• Gradient map and 1D LUT mapping.
• Sprite-rect recolor and contact-sheet generation for sprite sheets.
• Smart color analysis clusters and classifies a texture's colors (skin, cloth, metal, emission…).

// Replace a color in a texture (preview copy; source is never mutated)
Texture2D result = TextureRecolorUtility.ReplaceColor(
    source, fromColor, toColor, tolerance: 24, preserveAlpha: true);C#

💎 Materials

Shader-aware material recoloring and variant generation.

• Property-block recoloring — recolor a renderer without touching shared materials (see RecolorMaterialApplicator).
• Shader analysis detects the pipeline (Built-in / URP / HDRP / Shader Graph) and the available color/texture properties.
• Emission recoloring recognizes both _EmissionColor (Built-in/URP) and _EmissiveColor (HDRP/Lit).
• Material variants — spin off recolored material copies; Material Preset Libraries store reusable color presets.

📐 Meshes & Tilemaps

Vertex colors, UV/submesh workflows, and non-destructive tilemap recoloring.

Meshes

• Vertex color replacement with tolerance.
• UV islands and UV-rect masks, submesh descriptors and channel maps.
• Renderer hierarchy scanning to find and bind every renderer under a root.

Tilemaps

Recolor a UnityEngine.Tilemaps.Tilemap non-destructively: per-cell color replace, palette swap, HSV shift, multiply, tint, global tint, and color extraction. Per-cell colors live on the tilemap, not the tile, so a single shared tile recolors per cell.

🎭 Character Dye & Cosmetics

Player-facing customization: dye channels, cosmetic slots, deterministic randomize.

Dye channels

A RecolorProfile's Runtime Channels define named, palette-constrained dye channels (skin, hair, cloth, armor, weapon…) with default colors. A RecolorRuntimeController maps each channel to one or more renderer bindings and applies a RecolorRuntimeState at runtime.

// No-code: tick "Apply Defaults On Start" on the controller, or from code:
controller.SetChannelColor("cloth_primary", Color.cyan);
controller.ApplyProfileDefaults();   // build a state from the profile's defaultsC#

Cosmetics

CosmeticSlotApplicator toggles GameObjects per slot (helmet on/off, cape variants). CharacterRandomizer produces a deterministic dye state from a seed and a CharacterRandomizationRules asset (with locked channels and palette constraints).

💾 Save / Load

Serialize a player's appearance as lightweight data — not full textures.

• JSON payloads via RuntimeCustomizationStore / RecolorRuntimeState.ToJson().
• Compact, multiplayer-safe payloads via CompactRuntimePayloadCodec — small enough to sync over the network.
• PlayerPrefs persistence helpers, plus a checksum to detect tampering/corruption.

⚒ Batch & SDK

Generate variants in bulk and extend the framework.

• Batch processing with deterministic naming, dry-run, progress, cancellation and JSON/CSV reports (RecolorBatchProcessor).
• Validation reports flag missing scripts, broken sample references, duplicate channels and release issues.
• SDK — register custom shader profiles, processors, palette generators and validators; an extension registry discovers them by attribute.
• Headless runners — validation and build entry points for CI (-executeMethod).

📝 Editor Windows

Open from Tools → Ultimate Colorizer.

📙 Scripting API

The no-code components are thin wrappers over a clean, fully scriptable API.

using UltimateColorizer;

// 1) Recolor a renderer (non-destructive property block)
var applicator = go.AddComponent<RecolorMaterialApplicator>();
applicator.ApplyColor(Color.red);

// 2) Drive a recolor profile through the processing service
var registry = new RecolorProcessorRegistry();
registry.Register(new TextureRecolorProcessor());
var service = new RecolorProcessingService(registry);
RecolorResult result = service.Process(new RecolorContext(profile, target));

// 3) Runtime multi-channel dye
var state = new RecolorRuntimeState();
state.SetColor("skin", skinColor);
controller.Apply(state);
string json = controller.ToJson();   // save
controller.FromJson(json);          // loadC#

💡 Troubleshooting

Common issues and quick fixes.

❓ FAQ

Quick answers.

📬 Support

Need help? We're here for you.