Mods

A mod is a .NET library that adds windows and inserts its own interface into existing SpriteForge panels through ImGui.NET.

Mods run inside the program's process and have full access to the document and the system. Install only trusted DLLs.

Installation

At startup the program loads all top-level *.dll files from the folder:

%USERPROFILE%\AppData\LocalLow\BowPixel\Sprite Forge\Settings\Mods

The folder is created automatically. Copy a DLL there and restart the program. Examples are in the repository: Assets/InternalAssets/Mods/ExampleEmptyWindow~, AIModelFolders~, SentisImageGenerator~ (each has a mod.json and an Install-Mod.ps1 script).

The IMod interface

public interface IMod
{
    void OnLoad();
    void OnGui();
    void OnUnload();
}

OnGui is called in the UImGui layout loop, so you can call ImGui.NET directly inside it.

SpriteForgeModApi

Capability	Description
`CurrentDocument`, `Documents`	Metadata and the live `Bow.Document` instance; the list of open documents.
`CreateDocument`, `OpenDocument`, `SaveDocument`, `SaveDocumentAs`, `Generate`	Invoke the program's standard workflows.
`GetService<T>()`	Access to services: `Bow.Document`, `Bow.SpriteBuilder`, `Bow.Toolbar`, `Bow.FileSettings`, `Bow.Export.Export`, `Layers`, `NewFile`, `OpenFile`, `SaveFile`, `DocumnetSettings`, `PaletteGeneration`. Before the interface is initialized, Unity objects may be `null`.
`RegisterWindow(new ModGuiWindow { Id, Title, Draw })` / `UnregisterWindow(id)`	A named mod window.
`RegisterGui(Action)`	A callback executed every frame.
`Windows`	A list of `ModWindowInfo` (`Id`, `Title`, `IsOpen`, `IsBuiltIn`) for all built-in and mod windows.
`SetWindowVisible` / `GetWindowVisible`	Control the visibility of built-in panels by identifier.
`RegisterWindowContent(windowId, callback)` / `UnregisterWindowContent`	Insert your own interface inside a built-in panel.

Built-in window identifiers

canvas, guides, preview, tools, tool-settings, timeline, physics-animation, lighting, generated-sprites, result-library, history-performance, generation-toolbar, grid, tile-repeat, color-index, invert-colors, color-limit, ai-pixel-art, border, noise, auto-generator, effects, furniture, ui-generation, character-generation, user-settings, export, new-document, replace-color, generation-presets, expand-canvas. The ids palettes and mirror still work as content hooks inside Tool settings (the palette and the Mirror tool settings live there).

Example: content inside Preview

public void OnLoad() => SpriteForgeModApi.RegisterWindowContent("preview", DrawResultChoices);

private void DrawResultChoices()
{
    ImGui.Separator();
    ImGui.Text("My mod results");
    if (ImGui.Button("Use selected result"))
    {
        // Apply the selected result to the active document here.
    }
}

public void OnUnload() => SpriteForgeModApi.UnregisterWindowContent("preview", DrawResultChoices);

Building the example

The example references the generated Assembly-CSharp.dll, ImGui.NET and UnityEngine.CoreModule from the Unity project. Build:

dotnet build InternalAssets\Mods\ExampleEmptyWindow~\Build\ModApi.csproj
dotnet build InternalAssets\Mods\ExampleEmptyWindow~\Build\EmptyWindowMod.csproj

Tips

When changing document state, prefer the application's workflow methods - this keeps the interface and save tracking consistent.
Always unregister windows and content in OnUnload.
Row 0 of the document pixels is the top row. Do not add vertical flips unnecessarily; convert rows only at the boundary with external images.