Grimoire Legacy — Aseprite Extension
Installation
Run the setup wizard, configure ports, and bring up the local runtime.
Black Magik Installation Guide
The first time you launch Aseprite with Grimoire enabled, Black Magik runs a setup wizard. It checks for active setup ports, detects leftovers from earlier installs, opens the install docs in your browser, and then drives the full runtime setup from inside Aseprite.
What The Wizard Installs
| Step | What it sets up |
|---|---|
| UV + Python 3.13 | Installs UV if needed and provisions Python through it. |
| ComfyUI | Clones ComfyUI into the extension folder. |
| ComfyUI Manager | Installs the manager used for custom node maintenance. |
| Custom Nodes | Installs IPAdapter Plus, ComfyUI Essentials, OpenPose, DepthAnything V3, Inspyrenet Rembg, and PixelArt Detector. |
| Middleman Server | Sets up the Python service that bridges Aseprite, hosted APIs, and ComfyUI. |
| Preferences | Prompts for ports and generation-history limit after the files are ready. |
PyTorch installation is platform-aware:
| Platform | Installer behavior |
|---|---|
| Apple Silicon | Installs the current MPS-capable PyTorch nightly recommended for ComfyUI. |
| Windows / Linux | Uses UV automatic backend selection for NVIDIA CUDA, AMD ROCm, Intel XPU, and CPU fallback. |
| Intel Mac | Installs a CPU-compatible build; Apple Metal acceleration is supported on Apple Silicon. |
At server start, Grimoire probes CUDA/ROCm, Intel XPU, and Apple MPS. ComfyUI is forced into CPU mode only when PyTorch successfully confirms that none of those accelerators is available. A failed probe is logged as unknown and left to ComfyUI automatic device detection.
What The Wizard Asks You
Optional model downloads
After the runtime setup and preferences are complete, Grimoire opens Optional Model Downloads. Nothing is downloaded until you select one or more packs and click Download Selected Models.
- Download IPAdapter models installs the SDXL IPAdapter files and CLIP Vision encoder used by the IPAdapter tab.
- Download ControlNet models installs the SDXL ControlNet Union model used by the ControlNet tab.
- Download Wan models installs the two Wan 2.2 I2V diffusion models, UMT5 text encoder, and Wan VAE used by Animate Anything. This is a very large download.
- Skip closes the chooser without downloading models.
Downloads are resumable. Grimoire stops active runtime services before downloading and starts them again afterward when they were previously running. You can reopen the chooser later from Edit > Grimoire > Installation > Download Models.
If you enter IPAdapter, ControlNet, or Animate Anything without its required pack, Grimoire shows the missing files and opens the official model download page in your browser.
Previous installation cleanup
If Black Magik finds lingering black-magic files, it offers:
- Keep Existing (Faster): reuse the old install where possible
- Delete Existing (Cleaner): remove old files before reinstalling
- Cancel Installation: stop before any setup work starts
Preferred ports, history, and sampling
Near the end of setup, Grimoire asks for:
-
ComfyUI Port: default
8288 -
Middleman Port: default
8388 -
Generation History Save Limit: default
20 -
Show Workflow Queue: enabled by default
-
Review generated images before adding them: enabled by default; shows a temporary output canvas before creating layers
-
Show Seed Number: disabled by default; warning that it may cause the UI scrollbar to jump
Recommended screen scaling
The installer also recommends Aseprite Screen Scaling = 200% because Grimoire’s dialog is more comfortable at that size. It can open Preferences for you, but you can keep your current setting if you prefer.
Platform Behavior
| Platform | What to expect |
|---|---|
| Windows | The installer runs in the background to avoid repeated console flashes. |
| macOS / Linux | The installer opens a visible terminal alongside the in-Aseprite progress dialog. |
| macOS / Linux after setup | Black Magik auto-starts its runtime services when Aseprite launches. |
| Windows after setup | Use the menu or Settings tab to start the services when needed. |
What You Still Need To Provide
Git
The installer checks for git and opens the download page if it is missing.
- Windows: https://git-scm.com/downloads/win
- macOS: https://git-scm.com/downloads/mac
- Linux: https://git-scm.com/downloads/linux
Aseprite
Install Aseprite first: https://www.aseprite.org/
GPU drivers
If you want local GPU acceleration, install the correct drivers before or after setup:
- NVIDIA CUDA: https://developer.nvidia.com/cuda-downloads
- AMD ROCm: https://pytorch.org/get-started/locally/
- Intel XPU: https://pytorch.org/docs/stable/notes/get_start_xpu.html
- Apple Silicon: MPS is included in the macOS PyTorch build and selected automatically by ComfyUI
If the correct accelerator backend is unavailable during setup, PyTorch falls back to CPU. If Grimoire was installed before accelerator-aware setup was added, use Edit > Black Magic > Installation > Restart Installation to rebuild the environments with the current backend recipe. Normal startup never downloads or replaces PyTorch automatically.
Logs And Failure Recovery
If installation fails, Black Magik keeps a session log at:
- Windows:
%APPDATA%\\Aseprite\\extensions\\black-magic\\setup.log - macOS:
~/Library/Application Support/Aseprite/extensions/black-magic/setup.log - Linux:
~/.config/aseprite/extensions/black-magic/setup.log
The failure dialog includes Report Bug, which opens a prefilled issue link with setup context. Start there before manually deleting folders.
You can rerun the full wizard later from:
- Edit > Grimoire > Installation > Restart Installation
That flow rechecks ports, detects old files again, and lets you keep or clean them before reinstalling. The same Installation submenu also includes Uninstall Cleanup, which cleans Black Magik runtime files and opens Aseprite’s extensions folder so you can remove the extension cleanly.
First Steps After Setup
1. Open Grimoire
Go to Edit > Grimoire > Start Grimoire.
2. Start or verify the servers
Open Settings and use Start Servers or Server Status. You can also do this from Edit > Grimoire > Servers. If a configured port is already in use, Grimoire reports that the servers were not started instead of launching a conflicting runtime.
3. Decide between local and hosted generation
- Local tabs need imported models such as checkpoints and LoRAs. Use Installation > Download Models for the built-in IPAdapter, ControlNet, and Wan packs.
- API tab does not need local checkpoints, but it still uses the Black Magik runtime services.
4. Import a checkpoint if you want local generation
In Settings, choose checkpoints, select a .safetensors file, and click Import Model.