Mod Loader/Reference/Art API

ArtModApi replaces scene sprites, UI images, and renderer textures. All calls must run on Unity's main thread. For a pack without C#, start with Replace room art and sprites.

Register a picture

Put a 2048 by 1152 picture at images/picture.png beside your plugin DLL. This example replaces the daytime front-desk background. Use art-export to find names for other images. See Write a C# mod for project setup and compilation.

using System.IO;
using BepInEx;
using DressmakerMods;

[BepInPlugin("yourname.room-art", "Room Art", "1.0.0")]
[BepInDependency("yuu.dressmaker.mods", "0.6.93")]
public sealed class RoomArt : BaseUnityPlugin
{
    private ArtRegistration replacement;

    private void Start()
    {
        replacement = ArtModApi.Register("yourname.room-art.picture",
            new ArtReplacementDefinition {
                Kind = "image",
                AssetName = "fullImage",
                Scene = "PatternCutting",
                ObjectPath = "FrontDesk/Background",
                Image = "images/picture.png"
            }, Path.GetDirectoryName(Info.Location));
    }

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

ArtRegistration ArtModApi.Register(string id,
    ArtReplacementDefinition replacement, string assetDirectory)

ArtRegistration ArtModApi.RegisterTexture(string id,
    ArtReplacementDefinition replacement, UnityEngine.Texture2D image)

id must be unique across active registrations. Prefix it with your plugin ID. Register loads a PNG or JPEG from inside assetDirectory and destroys the loaded texture when you dispose the registration. Files are limited to 25 MB and 8192 pixels per dimension.

RegisterTexture uses a texture you've already loaded. It ignores the definition's Image field. Keep your texture alive until after disposing the registration; the loader won't destroy it. Both methods copy the definition, so editing that object later doesn't change the rule.

Replacement fields

C# property	JSON field	Value
Id	id	Required for each JSON entry; unique within that pack, up to 64 letters, numbers, dots, underscores or hyphens. C# uses the Register method's id argument instead.
Kind	kind	Required: sprite, image, rawImage or material.
AssetName	assetName	Required original sprite or texture name, up to 512 characters. Matching is case-sensitive.
Scene	scene	Optional exact scene name. Omit to match any loaded scene.
ObjectPath	objectPath	Optional exact hierarchy path from art-export. Omit to match any object.
MaterialIndex	materialIndex	Renderer material slot, starting at 0. Default 0; range 0 to 63. Used only for material replacements.
TextureProperty	textureProperty	Required shader texture property for material replacements, copied from art-export.
Image	image	PNG or JPEG path relative to the pack folder or assetDirectory. Paths outside that folder are rejected.
Priority	priority	Integer, default 0. Higher values win; the most recently registered rule wins ties.

A JSON pack's artReplacements array accepts 1 to 128 entries. If one entry fails to load, none of that pack's art replacements are kept, and the log explains which entry failed. Fabrics, accessories, and other content in the same pack are loaded separately.

Find targets from C#

ArtTarget[] ArtModApi.GetTargets()

Returns images in loaded scenes, including inactive objects. It won't list assets inside unloaded bundles, fonts, or a complete sprite animation as one target. Each target has Kind, AssetName, Scene, ObjectPath, MaterialIndex, TextureProperty, Width, and Height. Sprite dimensions describe its rectangle inside its texture atlas. Asset names remain the original names while a replacement is active.

The art-export console command writes these targets to BepInEx/config/DressmakerMods/art-reference.json with camelCase field names.

Refresh and remove

void ArtRegistration.Refresh()
void ArtRegistration.Dispose()

Refresh scans loaded scenes and applies the current rules. It doesn't reload files. To use a changed file or selector, dispose the old registration and register again. The loader checks for new objects about once a second while any art rules are registered.

Dispose removes the rule. A lower-priority rule takes over, or the original art returns. If the game changes an object's image, the loader checks the new image against your replacement rules. For materials, removing a replacement keeps changes the game made to its tint or other properties. Calling Dispose twice is harmless.

Notes for each image type

Sprites

Keep the original aspect ratio. The replacement keeps the sprite's size, pivot, and sliced borders. Use kind = "sprite" for a SpriteRenderer; its atlas material isn't a material replacement target.

UI images

An Image replacement changes its base sprite. A button can still show a different sprite when hovered or pressed. RawImage replacements change the texture directly.

Material textures

Texture scale and offset stay the same. The loader copies the material for the renderer it changes, leaving the shared source material alone.

Back to the Mod Loader guide