HueForge Studio

This guide is organised as Getting Started, a Workspace tour of every tab, deep-dives under Features, and a Reference section with asset types, the scripting API, troubleshooting, and FAQ.

New in 2.0 — an all-in-one colour toolset

Version 2.0 folds a whole product family into one asset (all reachable from the Palette tab and the Tools ▸ HueForge Studio menu):

⤓ Installation

Import the package and open the window. There is nothing to activate.

From the Unity Asset Store

What gets installed

Assets/HueForgeStudio/
  Runtime/                    // pipeline-agnostic types, palette/pattern assets, colour math
  Editor/                     // the window, tabs, operations, workers, IO, AI, CLI
    Window/Tabs/              // Paint, Palette, Inject, Repair, Batch, History, Settings, Help
    Operations/               // one class per non-destructive edit, history-aware
    Compute/                  // System.Math workers (background-thread safe)
    Gpu/                      // GPU Voronoi coagulation
    AI/                       // Claude / OpenAI / HTTP / Replicate providers
    CLI/                      // headless batch + verify entry points
  Shaders/                    // preview blit shaders for BiRP / URP / HDRP + Voronoi
  Palettes/                   // default output dir for palettes you create / import
  Documentation/              // you are hereProject

⚡ Quick Start

Your first non-destructive recolor.

✅ Requirements

What HueForge needs from your project.

🎨 Paint Tab

Solid, gradient, and pattern fills over a texture region, plus the Color Groups workbench.

Three paint modes

Region selection

Shift-drag on the preview to draw a rectangular region, or type explicit X / Y / W / H values. Zero-size clicks expand to the current brush size so a single click still paints. An eyedropper (I) samples a colour from the preview.

Emission & metallic companions

Solid, gradient, and pattern fills each have emission and metallic/smoothness variants that write to the matching companion map (e.g. _EmissionMap, _MetallicGlossMap) resolved for the active render pipeline.

On the same tab

• Color Groups workbench — group, parent orphans, coagulate, auto-clean, sort, diffuse. See Color Groups & Cleanup.
• A/B preview split-slider with BEFORE / AFTER labels.
• Colour-blindness simulator overlay (Protanopia / Deuteranopia / Tritanopia).
• Paint presets — save and reload mode + region + colour + gradient/pattern settings as a HueForgePaintPreset.

🌈 Palette Tab

A dedicated palette workspace: generate, audit, and exchange palettes inline.

The Palette tab (second tab, right after Paint) unifies three palette-centric tools. The same actions are also available as standalone wizards under the Tools menu.

⤓ Inject Tab

Composite multiple textures into a region with blend modes.

Build a stack of injection layers — each layer is a source texture with a blend mode, opacity, and optional mask. Reorder layers, toggle them, and flatten the stack to a single result that writes back to the target. The layer setup is stored on a HueForgePreset so you can reuse a compositing recipe across assets.

🔨 Repair Tab

Clean up and constrain texture data.

Repair settings can be saved as a HueForgeRepairPreset and replayed via recipes or batch.

☷ Batch Tab

Apply one preset to many assets, with a dry run and a revertable report.

↩ History & Undo

Per-asset operation log with real undo, redo, and reset.

Every operation is recorded with a thumbnail. HueForge keeps file-backed snapshots under the project Library/ (original, before, after) plus a persistent history cursor, so undo / redo / reset work even for imported PNG/JPG writeback — not just native texture assets.

• Undo / Redo / Reset from the window toolbar; Ctrl+Z / Ctrl+Y bridge into HueForge history where possible.
• Reset restores the very first state HueForge captured for the active target.
• List or thumbnail-grid view of the snapshot history.
• Recipe capture — turn the last N history steps into a replayable HueForgeRecipe. See Recipes.

🔧 Settings Tab

Per-project defaults and optional AI provider configuration.

🎨 Recolor & Grab

The all-in-one colour toolset: pull palettes from anything, recolor HD textures and sprites, and stylise — all non-destructive (a new asset is written; your source is never touched). Each tool is a one-click wizard under Tools ▸ HueForge Studio.

🎮 Color Groups & Cleanup

Turn a noisy texture into a small, editable palette of groups.

HueForge indexes a texture's unique colours and folds similar ones into groups. Recoloring a group recolors every pixel that belongs to it — one swap, many pixels. The workbench tools:

🎈 Gradients & Patterns

Richer fills than a flat colour.

Gradients

Define a multi-stop gradient and apply it across a region horizontally or vertically. Solid groups can be converted to gradients and back.

Procedural pattern generators

In Pattern mode, the Generate Procedural Pattern foldout offers thirteen generators that you can snap to the active palette or gradient:

A generated pattern can be stamped immediately or saved as a PatternAsset (texture + tiling / rotation / offset / tileable / opacity) for reuse.

🌈 Colour Harmony

Rule-based palette generation from one base colour — deterministic, offline, free.

Open the Palette tab (or Tools → HueForge Studio → Generate Harmony Palette...), pick a base colour and a scheme, and HueForge builds a palette on the colour wheel. Six schemes:

The colour math lives in ColorHarmony (runtime, unit-tested). Requesting more colours than a scheme's anchors pads with progressively value-varied repeats, so the count is always honoured and no swatch collapses to black.

// Generate a 5-colour triadic palette from steel blue
Color32[] swatches = ColorHarmony.Generate(
    new Color32(70, 130, 180, 255),
    ColorHarmony.Scheme.Triadic, count: 5);C#

♿ Accessibility (WCAG)

Audit a palette's contrast before it ships in your UI.

The accessibility report (in the Palette tab, or Tools → HueForge Studio → Palette Accessibility Report...) uses gamma-correct sRGB relative luminance — the same formula accessibility tools use — to compute WCAG 2.1 contrast ratios.

• Per-swatch readability — contrast against white and black text, which to use, and an AA / AAA / Fail badge.
• Low-contrast pairs — colour pairs too close to sit next to each other, with their ratio.
• Summary — minimum and average pairwise contrast across the palette.
• One-click auto-fix — choose an AA (4.5:1) or AAA (7:1) target and Save text-safe copy: every failing swatch is nudged in lightness (hue & saturation preserved) until black or white text passes, written to a new palette so the original is untouched. PaletteAccessibility.MakeTextSafe(colors, targetRatio) exposes the same fix in script.

var report = PaletteAccessibility.Analyze(colors, lowContrastThreshold: 3.0);
double ratio = PaletteAccessibility.ContrastRatio(fg, bg);   // 1..21
var level = PaletteAccessibility.ClassifyText(ratio);     // Fail / AA / AAAC#

Pair this with the Paint tab's colour-blindness simulator (Protanopia / Deuteranopia / Tritanopia) to check both contrast and colour-vision deficiency in one workflow.

🤖 AI Generation

Optional palette-from-prompt and texture-from-prompt, using your own key.

AI palette from text

In Settings, pick a provider and paste your key. Then in the Color Groups panel, open AI Palette, type a prompt, and click Generate Palette.

AI texture from an endpoint

Configure an HTTP image URL (raw PNG bytes or an auto1111-style {"images":["<base64>"]} response) or a Replicate token. Click Generate; the PNG lands in Assets/HueForgeStudio/Generated/ and auto-imports.

📤 Import / Export

Move palettes between HueForge and the rest of your toolchain.

Use the Palette tab, or the menu shortcuts Tools → HueForge Studio → Import Palette... and Export Palette....

PaletteIO.ExportAse(palette, "MyPalette.ase");
PaletteIO.ExportJson(palette, "MyPalette.json");
var colors = PaletteIO.ParseHexList(File.ReadAllLines("swatches.txt"));C#

📝 Recipes & Automation

Capture a sequence of edits and replay it on other textures.

In the History tab, click Capture Recent History as Recipe to bundle the last N operations into a HueForgeRecipe ScriptableObject. Drag another texture into the Replay target slot and click Replay Recipe.

Replay dispatches Solid Paint, Gradient, Posterize, Quantize, Snap-to-Palette, Channel Clamp, Remove-AA, Diffusion, Coagulate, Pixel Parenting, and AutoClean steps; steps that need extra context are skipped with a diagnostic rather than guessing.

Presets (paint / repair / batch / recipe) also export and import as deterministic UTF-8 JSON via PresetJsonIO, so they diff cleanly in version control.

📺 Render Pipelines

One asset, three pipelines — detected automatically.

PipelineProbe detects the active pipeline (Built-in, URP, or HDRP) and exposes the canonical shader property names so emission, metallic, and mask-map writes target the right channels. Preview blit shaders ship for all three.

🧩 Extensions (Plugin Bus)

Add your own tools without forking HueForge.

Implement IHueForgeExtension (id, display name, version). Add the optional IHueForgeTabExtension to contribute a custom tab that renders right alongside the built-in tabs. The ExtensionRegistry discovers implementations automatically via [InitializeOnLoad] — no manual registration.

public sealed class MyTab : IHueForgeTabExtension
{
    public string ExtensionId => "yourstudio.mytab";
    public string DisplayName => "My Tab";
    public string TabLabel => "My Tab";
    public System.Version Version => new(1, 0, 0);
    public System.Action<EditorWindow> DrawTab => w => { /* your IMGUI */ };
}C#

💻 Headless CLI / CI

Run HueForge from Unity batch mode for pipelines and automation.

Palette-signature verify

Fail a CI build when a texture's palette drifts from a known-good signature. A ready-to-use GitHub Action template ships at Documentation/CI/github-action.yml.

Unity.exe -batchmode -nographics -quit \
  -projectPath <PROJECT> \
  -executeMethod HueForgeStudio.EditorCli.HueForgeVerifyCli.VerifySignature \
  -hueforge-target Assets/.../Sword.png \
  -hueforge-expected-signature <hex> \
  -hueforge-report Library/HueForgeStudio/VerifyReport.csvShell

Batch apply / revert

HueForgeBatchCli.RunBatch() applies a HueForgeBatchWorkPreset to its targets and writes a CSV + JSON report; HueForgeBatchCli.RevertBatch() reverts the most recent (or a named) batch. HueForgeRecipeCli replays a recipe headlessly.

📁 Asset Types

The ScriptableObjects HueForge creates and consumes.

📚 Scripting API

The supported public surface for the 1.x line.

Everything public is documented in Documentation/PublicApi.md. Highlights:

• Runtime (HueForgeStudio.Runtime): ColorHarmony, PaletteAccessibility, PaletteAsset, PatternAsset, PaletteSignature, PipelineProbe, the preset/recipe types, HueForgeVersion.
• Operations (HueForgeStudio.EditorOperations): one public static class per edit (paint, gradient, pattern, repair, grouping, parenting, coagulate, auto-clean, diffusion, sort, harmony, extract), each returning a status struct and integrating with history.
• IO (HueForgeStudio.EditorPersistence): PaletteIO (parse/export GPL/ASE/PNG/hex/JSON) and PresetJsonIO; history is exposed via HueForgeHistoryService (HueForgeStudio.EditorCore).
• AI (HueForgeStudio.EditorAi): provider interfaces + Claude / OpenAI / HTTP / Replicate adapters + PromptServiceConfig.
• Extensions: IHueForgeExtension, IHueForgeTabExtension, ExtensionRegistry.

💡 Troubleshooting

Common issues and how to resolve them.

❓ FAQ

Quick answers.

📬 Support

Questions, bugs, ideas — we're glad to help.