Qud State Extracter

Game Website: Caves of Qud
Official Twitter/X: @cavesofqud

Overview

Qud State Extractor is a Harmony-based mod for Caves of Qud that logs all in-game player messages and player state to disk in plaintext and JSON formats.

Env Setup

1. Copy the template:

cp .env.template .env

2. Update BASE_FILE_PATH and any per-file output paths.

3. Keep ENABLE_VERBOSE_LOGS=false for normal play. Set it to true only when troubleshooting.

Env Loading Notes

core/EnvHelper.cs locates .env in the mod root (not ModAssemblies/) and expands variables like ${HOME} and ${BASE_FILE_PATH}.

Build

Runtime Compile (Source Mod)

1. Copy this mod folder into your Qud Mods/ directory.
2. Keep the .cs source files in place (core/exporters/patches/scrapers).
3. Launch the game; Qud compiles source mods at runtime into ModAssemblies/.

Prebuilt DLL (build.sh)

You can precompile a DLL locally with either:

./build.sh /path/to/CavesOfQud

or:

export CAVES_OF_QUD_DIR=/path/to/CavesOfQud
./build.sh

The script validates required references in: $GAME_DIR/CoQ_Data/Managed/

• Assembly-CSharp.dll
• 0Harmony.dll
• UnityEngine.CoreModule.dll

Output DLL:

• ModAssemblies/QudStateExtractor.dll

For deployment, copy ModAssemblies/QudStateExtractor.dll into your mod folder’s ModAssemblies/ directory in the Qud Mods/ path.

Logging Rules

All Unity logging is routed through core/Log.cs:

• Log.Info(...): verbose-only, gated by ENABLE_VERBOSE_LOGS=true
• Log.Warn(...): always logged
• Log.Error(...): always logged

This keeps normal gameplay logs quiet while preserving warnings/errors.

Core Components

• core/QudStateExtractorInit.cs: Harmony mod bootstrap that initializes env/config and applies patches.
• core/ReflectionHelpers.cs: shared reflection helpers for safe property/field/method access against Qud runtime objects.
• core/EnvHelper.cs: .env loader and variable expansion.
• core/Log.cs: centralized Unity logging wrapper with verbose gating.
• core/ExportWriter.cs: shared JSON read/write helpers for exporter output paths from .env.

Exporters

• exporters/UIStateExporter.cs: emits current_view.json snapshots describing active UI/game view state.
• exporters/GameStateExporters.cs: exports player/world/quest/journal/dialogue/POI state snapshots.
• exporters/MenuExporters.cs: exports menu-oriented snapshots (ability, equipment, skills, status, tinkering, pick-item, trade).
• exporters/MergeHelpers.cs: merges scraped quick-key/bottom-bar data into exporter JSON records.
• Dependency flow: scrapers gather window/menu/key data, MergeHelpers aligns it to export rows, and all final writes go through core/ExportWriter.cs.
• Export logs are summary-only in verbose mode; failures are emitted as errors.

Patches

• patches/CoreLifecyclePatches.cs: hooks core lifecycle/game events (startup, stats, quests, dialogue, player message queue) and triggers GameStateExporters outputs.
• patches/MenuScreenPatches.cs: hooks menu/screen lifecycles (ability, equipment, skills, status, tinkering, trade, nearby items) and drives MenuExporters plus MergeHelpers updates.
• patches/StatusScreensHubPatch.cs: hooks modern StatusScreensScreen hub/tab updates and routes bottom-bar + quick-key merges for skills/status/equipment/tinkering exports.
• patches/DialogueAndPopupPatches.cs: hooks popup/dialog-style UI and pick-item flows to export popup payloads and pick-screen menu/key data.
• patches/UIStatePatches.cs: hooks UIManager.Update and triggers UIStateExporter.ExportCurrentView() to keep current_view.json in sync with active UI state.
• Patch flow: Harmony hooks -> scraper capture (QuickKeyScraper / BottomBarScraper) -> merge/export (MergeHelpers / MenuExporters / GameStateExporters) -> ExportWriter.
• Patch logging is failure-focused with no per-call informational spam.

Scrapers

• scrapers/WindowScraper.cs: resolves the current modern UI window component for downstream exporters/scrapers.
• scrapers/BottomBarScraper.cs: extracts normalized bottom-bar actions (text/hotkey) from active windows for exporter payloads.
• scrapers/QuickKeyScraper.cs: extracts per-row quick-key bindings and related identifiers (for abilities/items/equipment lists).
• scrapers/MenuItemHelpers.cs: shared menu-option normalization/dedup and command-to-hotkey resolution used by scraper pipelines.
• scrapers/StringHelpers.cs: strips Qud markup from scraped UI text before export.
• Usage: exporters can call WindowScraper.GetCurrentWindow() and pass the result to BottomBarScraper.ScrapeFromWindow(...) when building UI snapshots.

Vendored Dependency

• core/MiniJSON.cs is a vendored MiniJSON implementation (Calvin Rien, MIT license) used for lightweight JSON parsing/serialization.
• The original license header is preserved in the source file.

Limitations

• .env must exist and be correctly formatted
• Currently Linux-only (Windows support untested)

License

MIT-style. Fork it, adapt it, use it.

Created by: piestyx First released: 2025-06-24