RPG Assets

Local-first web app for generating print-and-play RPG creature assets with ComfyUI.

The current slice focuses on paper minis: the app generates a single front-facing creature image, stores the generation settings, and builds printable PDF sheets with fold/cut guides.

Status

This is an experiment, not a packaged release. It is intended to run locally and keep generated assets, model files, ComfyUI, and runtime settings outside git.

Features

• SvelteKit local web app for creature paper minis.
• ComfyUI image generation provider.
• SD 1.5 checkpoint + PrintableHeroes-style LoRA workflow.
• Prompt suggestions from prompt_library/.
• Universal PrintableHeroes prompt builder based on common tags from the prompt library.
• Generated asset metadata stores prompt, negative prompt, seed, dimensions, model settings, and print size.
• A4 printable PDF export with mirrored fold layout, tabs, cut guides, and optional nameplate.

Requirements

• Nix with flakes enabled.
• A local GPU setup supported by ComfyUI/PyTorch.
• v1-5-pruned-emaonly.safetensors SD 1.5 checkpoint.
• printableheroes-paperminis-v1-3.safetensors LoRA, or another LoRA configured in the app.

The Nix shell provides Node, pnpm, Python, uv, sqlite, and a local rpgassets-comfyui launcher.

Setup

Enter the dev shell:

nix develop

Install JavaScript dependencies:

pnpm install

Put model files in the ignored runtime directories:

runtime-models/checkpoints/v1-5-pruned-emaonly.safetensors
runtime-models/loras/printableheroes-paperminis-v1-3.safetensors

Model files are intentionally not committed. Download them from their original sources and follow their licenses/terms.

Running

Start ComfyUI in one terminal:

nix develop
rpgassets-comfyui

Start the app in another terminal:

nix develop
pnpm run dev

Open the local URL printed by Vite, usually http://localhost:5173.

ComfyUI Launcher

The dev shell provides rpgassets-comfyui. On first run it:

• clones ComfyUI into runtime-comfyui/ComfyUI
• creates runtime-comfyui/venv
• installs ComfyUI Python dependencies with uv
• links local checkpoints from runtime-models/checkpoints/
• links local LoRAs from runtime-models/loras/
• starts ComfyUI at http://127.0.0.1:8188

Optional VRAM mode arguments can be passed through RPGASSETS_COMFY_ARGS:

RPGASSETS_COMFY_ARGS="--lowvram" rpgassets-comfyui
RPGASSETS_COMFY_ARGS="--highvram" rpgassets-comfyui

--highvram tries to keep more model data loaded, but can fail on 6 GB GPUs. --lowvram is safer but may unload more aggressively.

Configuration

Use /settings in the app to configure:

• ComfyUI URL
• checkpoint name
• LoRA name
• LoRA strength
• VRAM mode note for the launcher
• whether to try keeping the model loaded

Defaults can also be overridden when starting the app:

COMFYUI_URL=http://127.0.0.1:8188 COMFYUI_CHECKPOINT=other-model.safetensors COMFYUI_LORA=other-lora.safetensors pnpm run dev

Runtime settings are saved under storage/, which is ignored by git.

Prompt Library Analysis

The repository includes a script to identify common tags and words from prompt_library/:

pnpm run analyze:prompts

Use this when changing the universal prompt or preparing captions for a new LoRA.

Project Layout

• src/routes/+page.svelte: generator form and asset gallery.
• src/routes/+page.server.ts: generation action and asset loading.
• src/routes/settings/: local model/LoRA settings UI.
• src/lib/creatures.ts: creature types, print sizes, universal prompt builder, generation preset.
• src/lib/server/comfyui.ts: ComfyUI workflow integration.
• src/lib/server/print.ts: PDF sheet generation.
• src/lib/server/storage.ts: local runtime asset storage.
• prompt_library/: prompt examples used for suggestions and analysis.
• scripts/analyze-prompt-library.mjs: prompt-library frequency analysis.

Runtime Data

The following paths are ignored and should stay local:

• runtime-models/: checkpoints and LoRAs.
• runtime-comfyui/: cloned ComfyUI checkout and Python venv.
• storage/: generated images, asset metadata, and local settings.
• .pnpm-home/ and node_modules/: package manager/dependency state.

Verification

pnpm run check
pnpm run build

Run these inside nix develop if the required tools are not available globally.

Roadmap

See TODO.md for planned support for props, terrain grids, transparent backgrounds, external images, multi-unit naming, saved print pages, and custom LoRA workflow notes.

License

Application code is licensed under the MIT License. See LICENSE.

Generated images, third-party model files, LoRAs, ComfyUI, Stable Diffusion checkpoints, and any source datasets/prompts may have separate licenses or usage terms. Review those before publishing or redistributing assets.