✦ NIGHTRUN ✦ Overnight Forge Randomizer (Low-High VRAM Optimized)

Installation — Folder Structure

Nightrun expects to live two levels inside your WebUI folder:

YOUR-WEBUI-FOLDER\
  workflows\
    nightrun_2.0\   ← here

A local Forge companion that builds structured prompt batches, runs them overnight, manages metadata-based upscales, and watches the boring parts, so your PC can do the babysitting for once.

GitHub Link: id="nightrun-2.0">Nightrun 2.0

A portable workflow system for Stable Diffusion Forge / Forge-Neo.

Nightrun is not a model. Not a LoRA. Not a prompt file.

It is the system that sits beside Forge and turns a messy local generation setup into something that can run for hours — without you checking whether the prompt broke, a LoRA name was wrong, the GPU is cooking itself, or the batch slowly turned into repetitive garbage.

Nightrun is built for long local runs, editable prompt pools, metadata replay, LoRA-aware batching, upscale workflows, cooldown logic, and controlled randomness.

Set the run. Leave it alone. Come back to something organized, replayable, and worth sorting through.

What Nightrun Does

Nightrun builds prompts from editable pools, sends jobs through Forge, writes replayable metadata, manages upscales, scans LoRAs, protects long runs with cooldown logic, and keeps the whole thing configurable.

It is made for people who want big batches without babysitting every prompt, every upscale, every progress bar, and every local setup problem.

Controlled chaos. Not prompt soup.

What's New in 2.0

Modular Architecture

The engine was split from a single ~2055-line file into a purpose-driven module system:

nightrun_runtime.py — core shared logic
prompt_engine.py — pool loading, weighted selection, prompt composition
lora_resolver.py — LoRA scanning, aliases, tag construction
forge_client.py — Forge API, txt2img/img2img, GPU guards
runner.py — execution modes, output folders, cleanup, cooldowns, summaries
validation.py — pool validation and dry-run reporting
nightrun_engine.py — compatibility shim for older imports

nightrun.py is now a thin entrypoint that only imports and runs main().

Three-Engine Prompt Routing

Prompt generation now routes through three distinct builders, selected by weighted random choice (default 1/1/1). You can control routing via prompt_engines in config, or disable it to revert to legacy behavior.

Classic — Standard pool sampling with optional world module support. Closest behavior to 1.5, cleaned and optimized.

Combinator — Builds on Classic output by applying controlled transformations:

Internal combinators modify existing elements (e.g. a katana becomes a burning variant)
External combinators inject additional motifs (e.g. surreal, cursed, steampunk layers)
At least one combinator fires per prompt, capped at two

Franchise — Forces generation through a world module from franchise_catalog.py. All visual elements are sourced from that universe for full coherence. Falls back to Classic if no module is available.

Prompt Cleanup Pipeline

A post-processing stage via prompt_cleanup now runs after every engine:

Duplicate comma-tag removal
Concept-family repetition control
Compact SD-style prompt length enforcement
Removal of redundant subject labels when already implied

Consistent prompt structure across all three engines.

Prompt Pools — Full Rebuild

All pools were rebuilt for SD-style tag efficiency. Verbose prose entries are gone. 2.0 uses compact, composable tags throughout.

Pool 1.5 lines 2.0 lines concept.txt 3,601 154 genre.txt 8,317 2,743 glamour_pose.txt 4,241 761 clothing.txt 1,801 721 character.txt 701 44 body_focus.txt 1,105 481 sensual_layer.txt 1,921 529 hair.txt 2,401 790

Removed: character_loras.txt, style_loras.txt, lora_sampler_speed.txt

Added: genre_core.txt (69 lines), genre_root.txt (475 lines)

A curated weighting system (curated_top_count / curated_top_weight) boosts high-quality early entries without removing full pool diversity.

Franchise Catalog — Expanded to ~50 Modules

Modules now use full dictionary-based definitions instead of compact tuples. The catalog grew from ~24 to ~50 entries:

alien batman bloodborne cowboy_bebop doctor_who dungeons_and_dragons elder_scrolls evangelion final_fantasy_vii game_of_thrones halloween hellraiser lord_of_the_rings matrix midsommar nier_automata nightmare_on_elm_street persona pokemon scream shadowrun terminator the_conjuring the_ring the_witcher vampire_masquerade x_men zelda

New filtering controls without touching the catalog directly: enabled_module_ids / disabled_module_ids / enabled_source_names / disabled_source_names / label_allow_patterns / label_block_patterns

Selection Memory — Retuned

Larger recent history windows across categories
Reduced repetition penalties for more natural variation
Added concept-level tracking via recent_concepts
Dedicated repetition control for candle/light motifs
Curated weighting for high-quality biasing

Config Changes

fixed_suffix updated for sharper SD output:

Before: clean coherent design, sharp focus, high detail, polished lighting
After: crisp linework, sharp focus, high detail, clear material texture, clean color separation, high micro-contrast, dramatic lighting
base.steps_min raised: 30 → 50
Output folders now use nightrun-YYYYMMDD-HHMMSS
--reset-local now preserves local tuning instead of overwriting it

New VRAM Profile — `tuned_6gb`

Setting Value Base resolution 1344×768 Upscale resolution 3072×1728 Steps 65 LoRA cap 7 VRAM threshold ≤ 6144 MB

NSFW — sensual_layer Expansion

The sensual_layer pool was fully reworked to properly support explicit NSFW generation paths. It now includes dedicated nudity, erotic styling, body exposure, lingerie, fetish-adjacent aesthetic, and mature composition tags designed to integrate cleanly with the SD-style prompt system and franchise/genre routing.

NSFW is enabled by default. For SFW-only runs, open config.json, find sensual_layer, and set "chance": 0.

Core Features

Editable Prompt Pools

Nightrun uses plain .txt prompt pools instead of one giant hardcoded prompt. Edit pool files to change how the whole machine behaves:

concept genre genre_core genre_root character hair eyes clothing pose glamour_pose expression sensual_layer body_focus equipment environment lighting camera effects style_layer color_grade composition detail and more.

The world module system is deeper and optional. The pool system is where most users should start.

Controlled Randomness

Nightrun is random — but not stupid-random. You can configure:

Pool chances and pick counts
Boosted chances when related pools appear
Base step ranges
LoRA chances, weight ranges, and caps
World module and fusion mode chances
Cooldown timing and upscale behavior
Selection memory and color repetition penalties

You are not stuck with one fixed behavior. Tune the machine until it behaves like your machine.

Selection Memory

During a run, Nightrun remembers recent choices and penalizes repetition. It tracks broad color families — blue, cyan/teal, red, purple, green, gold, black, silver, iridescent — so if a batch starts drifting into one color mood, it pushes away.

This is one of the main reasons long runs do not feel repetitive.

Rare Detail Control

Some details are only interesting when they stay rare. Heterochromia, for example, can be configured so it does not take over an entire batch. Special things stop feeling special when every third image has them.

LoRA Handling

Nightrun does not blindly slap LoRAs into the prompt. It can:

Scan local LoRA folders and resolve names
Use aliases and soft-match ugly filenames
Skip missing LoRAs without crashing the run
Randomize LoRA weights within configured ranges
Add synergy/support LoRAs with controlled chances
Cap random and total LoRA counts
Deduplicate final LoRA tags

Local LoRA libraries are messy. Civitai names, trigger names, and local filenames are often all slightly different. Nightrun tries to survive that.

Coherent World Modules

The normal prompt pools are the everyday engine. The world module system is the coherence layer.

When it activates, Nightrun selects a world/franchise module and pulls related elements from the same source family — character archetypes, outfits, environments, props, factions, technology, magic systems, lighting mood, color palettes, cinematic language, and more.

The goal is not to replace the normal pools. The goal is to give the run a coherent themed spine when that system activates.

Fusion mode allows controlled cross-world combinations while reducing risky generic pool chances — unusual mixes without the machine blindly dumping everything into one prompt.

Long-Run Safety

GPU temperature pause — Nightrun watches GPU temperature through nvidia-smi. If the GPU gets too hot, it pauses. When it cools below the configured resume threshold, it continues.

VRAM chill sessions — For big batches, Nightrun schedules random cooldown sessions. Run several generations, pause for a few minutes, let the system settle, continue. Small thing. For overnight workflows it matters.

Between-image rest — Configurable sleep time between images so the machine is not being tortured nonstop.

Nightrun is not just "go fast." It is "keep going safely."

Upscale Workflow

Nightrun supports both scheduled upscale workflows and metadata-based re-upscaling. It can:

Generate base images and upscale during full runs
Auto-upscale low-step base renders
Accept drag-and-drop metadata for upscaling
Recreate from metadata if needed
Write new metadata beside upscaled images
Chain later upscales from previous upscale metadata

A fast base image does not have to stay a rough base image. Low-step renders can go through upscale logic and recover quality without burning time on every single base generation.

Metadata Replay

Every image gets a metadata sidecar with everything important saved:

seed prompt negative prompt selected pools selected modules LoRAs LoRA sources base steps status upscale reason errors GPU info

So later, you are not staring at a good image wondering what made it. The answer is saved beside it.

Validation and Dry-Run

Validation mode checks pool loading, prompt formatting, LoRA resolution, missing resources, alias behavior, and generation logic — before wasting GPU time.

Dry-run mode writes prompt and metadata without calling Forge image generation. See what the run would do before committing to a real batch.

Measure twice. Render once.

Prompt Variety Analyzer

A built-in tool scans old metadata and reports:

Repeated categories, colors, and modules
Repeated prompt fragments
World module usage patterns
Exact prompt repeats
Signs that a batch is becoming too samey

Tune the machine instead of guessing.

Outputs

Each run creates an organized folder:

nightrun-YYYYMMDD-HHMMSS/
  0001_base_WIDTHxHEIGHT.png
  0001_upscale_WIDTHxHEIGHT.png
  0001_prompt.txt
  0001_metadata.json
  summary.json
  run.log
  contact_sheet.jpg
  validation_report.json

Exact files depend on the run mode.

Basic Usage

Task Launcher First-time setup Run First Setup.bat Validate before rendering Run Validation Stress Test.bat Preview one prompt, no render Run One DRY TEST.bat Base generation only Run Nightrun BASE only.bat Full run with scheduled upscale Run Nightrun FULL upscale.bat Re-upscale from metadata Run 2x Upscale From Metadata.bat Analyze prompt variety Run Prompt Variety Analyzer.bat Stop cleanly after current image Stop After Current Image.bat

Metadata Upscaling

py upscale_from_metadata.py "D:\renders\0001_metadata.json" --config config.local.json --scale 2

Force base image as source:

py upscale_from_metadata.py "D:\renders\0001_metadata.json" --config config.local.json --source base --scale 2

Use an existing upscale as source:

py upscale_from_metadata.py "D:\renders\0001_metadata.json" --config config.local.json --source upscale --scale 2

Dry-run the upscale:

py upscale_from_metadata.py "D:\renders\0001_metadata.json" --config config.local.json --scale 3 --dry-run

First-Run Setup

The setup script creates a local config for your machine. It will:

Ask for your Forge / Forge-Neo path and output folder
Detect your VRAM profile
Check checkpoint path and count local LoRAs
Check for Ultimate SD Upscale
Create config.local.json and desktop shortcuts

The shared config.json stays portable. Your private machine paths stay in config.local.json. The project can be shared without leaking your local folder structure.

Recommended For

Nightrun is useful if you:

Use Forge / Forge-Neo locally
Generate in large batches or overnight runs
Want editable prompt pools instead of hardcoded prompts
Use many LoRAs and want safer handling
Want metadata replay for good images
Want upscaling tied to generation metadata
Want less repetitive outputs over long runs
Want a workflow you can tune instead of replace

Notes

Nightrun does not include checkpoints, LoRA files, model files, Forge itself, or Ultimate SD Upscale. You need your own local Forge / Forge-Neo setup and your own models.

Franchise and world module names are used as inspiration labels for prompt organization only.

License / Usage note

Use this with models, LoRAs, and extensions you are allowed to use.
Franchise module names are inspiration labels for prompt organization. Nightrun does not include model files, LoRA files, checkpoints, or copyrighted assets.
Nightrun is a prompt generation and batch runner tool. It does not include, distribute, or download any AI models, checkpoints, LoRAs, extensions, or generated images. All content is produced locally using software and model files you have installed yourself.
You are solely responsible for the models and extensions you use, the content you generate, compliance with third-party license terms, and compliance with the laws of your jurisdiction.
NSFW generation is supported. It is your responsibility to ensure any explicit content you generate is legal in your jurisdiction. This tool must not be used to generate illegal content of any kind.
Nightrun is provided as-is, without warranty of any kind.

Built for the dark hours between intention and discovery.