Mod Loader/Reference/Pencil color API

The sketchbook pencil uses a palette of color swatches. A content pack can change those swatches with mod.json. A C# plugin can change them while the game is running, or select the pencil's drawing color directly.

Make a palette pack

Create Mods/MutedPencils/mod.json in your game folder and paste this into it:

{
  "id": "example.muted-pencils",
  "name": "Muted Pencils",
  "version": "1.0.0",
  "pencilPalette": {
    "replace": true,
    "colors": ["#F4A7B9", "#C3B1E1", "#A8D5BA", "#A7C7E7", "#F5DEB3", "#575267"]
  }
}

Restart the game, then open the pencil's color picker in the sketchbook. Set replace to false to add your colors after the existing swatches instead. You can put pencilPalette in a pack that already adds fabrics or other content; it doesn't need a separate folder.

Field	What to enter
`replace`	`true` replaces the base palette. `false`, the default, adds swatches.
`colors`	An array of 1–128 colors in `#RRGGBB` or `#RRGGBBAA` format. The optional last two digits set opacity: `FF` is opaque, `00` is transparent.

To share the pack, ZIP its folder and install it through Mod Manager → Install/Update Mod. The manager accepts packs containing only a pencil palette. Disable the pack and restart to remove its swatches.

Pack folders load alphabetically. If two packs replace the palette, the later one wins. Colors added with replace: false remain after the replacement palette.

If the colors don't fit on one page, use the arrow buttons in the palette to see the rest.

Add your own categories

Use categories to give your colours their own pages in the picker. The category name and left/right arrows appear in a new row above the swatches. For example, this pack adds Pastels and Earth tones:

{
  "id": "example.muted-pencils",
  "name": "Muted Pencils",
  "author": "Example",
  "version": "1.1.0",
  "description": "Pastel and earth-tone categories for the sketchbook pencil.",
  "pencilPalette": {
    "categories": [
      {
        "id": "pastels",
        "name": "Pastels",
        "colors": [
          "#F4A7B9",
          "#C3B1E1",
          "#A8D5BA",
          "#A7C7E7",
          "#F5DEB3",
          "#575267"
        ]
      },
      {
        "id": "earth-tones",
        "name": "Earth tones",
        "colors": [
          "#EEE4CD",
          "#CDAA80",
          "#A66D4F",
          "#794A34",
          "#4D3225",
          "#536645"
        ]
      }
    ]
  }
}

Save this as Mods/MutedPencils/mod.json, restart the game, then open the pencil's colour picker. Use the header arrows to switch categories. The arrows wrap around at either end. Switching categories keeps the current drawing colour until you choose another swatch.

Default contains the game's palette and changes from older palette packs. A category-only pack leaves those colours alone. You can include the existing colors and replace fields alongside categories to change Default too. replace: true requires a colors list and only replaces Default.

Category field	What to enter
`id`	A unique ID within this pack, up to 64 characters. Use letters, numbers, dots, underscores, or hyphens.
`name`	The name above the swatches, from 1 to 60 characters. Short names fit best.
`colors`	From 1 to 128 colours in `#RRGGBB` or `#RRGGBBAA` format.

A pack can add up to 32 categories. They appear in the order listed, after categories from packs loaded earlier. A category with more colours than fit in the grid has page arrows among its swatches and a page number beside its name. The header arrows switch categories.

If a category fails to load, that pack's pencil changes are removed and the error appears in BepInEx/LogOutput.log. Check for duplicate IDs, a missing name, or a colour without its #.

Change colors from C#

Use PencilColorModApi from DressmakerMods. You can register colors in Awake, before the sketchbook opens. Keep the returned handles so you can dispose of them when your plugin unloads. Call the API on Unity's main thread, such as from Awake, Update, or a settings button. RGBA components must be finite numbers between 0 and 1.

using System;
using BepInEx;
using DressmakerMods;
using UnityEngine;

[BepInPlugin("example.pencils", "Pencil Example", "1.0.0")]
[BepInDependency("yuu.dressmaker.mods", "0.6.82")]
public sealed class PencilExample : BaseUnityPlugin
{
    private IDisposable pink;

    private void Awake()
    {
        pink = PencilColorModApi.AddColor(
            "example.pencils.pink", new Color(0.96f, 0.65f, 0.73f));
    }

    private void OnDestroy() => pink?.Dispose();
}

To replace the base palette, use SetPalette instead. Declare palette as an IDisposable field and dispose of it in OnDestroy, just like pink above.

palette = PencilColorModApi.SetPalette("example.pencils.palette",
    Color.black, Color.white, new Color(0.96f, 0.65f, 0.73f));

Each registration needs its own ID. If several plugins replace the palette, the most recently registered replacement wins. Disposing its handle brings back the previous replacement, or the game's original palette. Added swatches stay available regardless of which replacement is active. Removing a palette doesn't change the selected drawing color or erase painted areas.

Register a category

Store the returned handle as an IDisposable field, just like the swatch above:

pastels = PencilColorModApi.AddCategory("yourname.pencils.pastels", "Pastels",
    new Color(0.96f, 0.65f, 0.73f),
    new Color(0.65f, 0.78f, 0.91f));

Dispose pastels in OnDestroy to remove it. Category IDs share the same registration namespace as AddColor and SetPalette; use a different ID for each call. The ID default is reserved.

Once IsReady is true, call GetCategories() to get each category's Id and Name. SetCategory(id) selects one without changing the pencil colour. GetSelectedCategory() returns its ID, and GetColors() returns that category's full palette, including colours on other pages.

JSON category IDs use pack.PACK_ID.pencil-category.CATEGORY_ID in C#. For the example above, use pack.example.muted-pencils.pencil-category.pastels. Removing the selected category switches back to Default. The category selection lasts until the picker is recreated or the game closes.

Select a drawing color

Wait until the sketchbook is ready before reading its colors or selecting one:

ready = PencilColorModApi.WhenReady(() =>
{
    PencilColorModApi.SetSelectedColor(new Color(0.96f, 0.65f, 0.73f));
});

Keep ready as an IDisposable field and dispose of it in OnDestroy too. The callback runs once, immediately if the picker already exists. Otherwise it waits for the picker to initialize, which may not happen until the player first opens it.

SetSelectedColor changes the pencil's visible color and the color used for new fills. It doesn't pick up the pencil or repaint existing areas. The selected color doesn't have to be a palette swatch. If the picker is already open, cancelling it keeps the color selected by your mod.

Methods

IDisposable AddCategory(string id, string name, params Color[] colors): Adds a named category with 1 to 128 colours. Can be called before the picker exists.
PencilColorCategory[] GetCategories(): Returns category IDs and names, starting with Default. Requires IsReady.
string GetSelectedCategory(): Returns the visible category's ID. Requires IsReady.
void SetCategory(string id): Shows a category's first page. Rejects an unknown ID. Requires IsReady.
IDisposable AddColor(string id, Color color): Adds one swatch. Dispose the handle to remove it.
IDisposable SetPalette(string id, params Color[] colors): Registers a replacement base palette containing 1–128 colors. The array is copied.
Color[] GetColors(): Returns a copy of all colours in the selected category. Default includes added swatches. Requires IsReady.
Color[] GetOriginalColors(): Returns a copy of the game's palette before API changes. Requires IsReady.
bool TryGetSelectedColor(out Color color): Returns the drawing color, or false if the sketchbook isn't ready.
void SetSelectedColor(Color color): Selects the drawing color. Requires IsReady.
bool IsReady: Whether an initialized sketchbook picker is available.
IDisposable WhenReady(Action callback): Runs a callback once the picker is available. Dispose to cancel a callback that hasn't run yet.

Back to the Mod Loader guide