Grimoire Legacy — Aseprite Extension

These docs cover the legacy Aseprite extension. For the standalone editor, see Grimoire Standalone .

Grimoire is Black Magik’s local-first Aseprite extension for AI pixel art, reference-guided generation, and retro game asset cleanup. It connects your local ComfyUI workflows directly to the Aseprite canvas, then previews compatible results on a temporary canvas before returning selected images as new layers, frames, or output sprites so you can generate, refine, convert, and export without leaving your editor.

The core workflow is built around ownership: use your installed checkpoints, LoRAs, IPAdapter assets, ControlNet models, custom nodes, and local project files. Hosted API providers are available when you want them, but they are secondary options rather than the center of the product. The Tools tab handles palette reduction, neural pixelization, configurable Wang and Blob tilesets, resizing, reference extraction, custom workflow runs, and other practical cleanup steps after generation.

Main Areas

First Session Checklist

1. Run the installation wizard. It sets up UV, Python 3.13, ComfyUI, PyTorch, required custom nodes, and the middleman server. Model files are not part of the base setup.
2. In the post-setup chooser, optionally select the IPAdapter, ControlNet, or Wan packs and click Download Selected Models. You can reopen it later from Edit > Grimoire > Installation > Download Models.
3. Open Edit > Grimoire > Start Grimoire. If no sprite is open, Grimoire creates a new 1024x1024 file automatically.
4. Make sure the runtime services are ready. On macOS and Linux they usually auto-start after setup; on any OS you can use Settings > Start Servers or the Edit > Grimoire > Servers submenu.
5. If you want local generation, import at least one checkpoint in Settings > Import Model.
6. Choose the workflow that matches the job:
   • Local prompt/model work: Text to Image, Img2Img, In/Outpaint, IPAdapter, ControlNet
   • Hosted generation: API
   • Animation master preparation: Animate Anything
   • Cleanup and conversion: Tools
7. Generate once, use Save Workflow to keep useful setups, and use Settings > Workflow History when you want to reload saved or automatically recorded runs.

What Persists

• Grimoire remembers the last-used settings for each major tab.
• Animate Anything’s controls persist, but its locked master palette lasts only for the current Grimoire session.
• Successful local generations are auto-saved to workflow history and pruned by your history limit. Manual saved workflows are kept separately.
• The dialog position and size are remembered between sessions.
• The Workflow Queue visibility preference is remembered; closing the queue window hides it until you turn it back on in Settings.
• Output review is enabled by default and remembered; disable it in Settings > Output Handling to restore direct layer creation.
• The seed number is hidden by default to reduce Aseprite scrollbar jumps. Enable Settings > Sampling > Show Seed Number when you need to inspect or edit exact seeds.

Use Settings > Clear Saved Tab Settings if the UI state becomes stale, and Settings > Reset Generation Bounds if the dialog opens in an awkward size or position.

Good Habits

• Leave the servers running for the session unless you need to free resources or reload nodes.
• Save local workflows once you find a model, prompt, and sampler combination that works.
• Use the API tab when you want hosted generation, but remember Grimoire still needs its local runtime services and an Aseprite canvas to receive the result.
• Use Tools > Pixelization or Tools > Palette Reduction after generation when you need cleaner palette control or a more retro finish.
• Use Animate Anything to prepare a canonical source, then Tools > Palette Transfer to enforce its colors across every frame of another sprite.
• Use the Tools tab for structure-first tasks like ControlNet reference extraction or workflow JSON experimentation.

System Requirements

Additional disk space is needed for extra models. SDXL checkpoints are typically 6-7 GB each.