Kingdom Cheat: Deliverance II — working notes

The project's rules and layout. This page was an untracked CLAUDE.md in the working tree until 2026-08-08 — it was never committed, so there is no history to rewrite here. Nothing loads it automatically now; read it before starting work.

What this is

A desktop overlay for Kingdom Come: Deliverance II. It's a searchable database of console commands, items, perks, buffs and skills: the user fills in parameters, clicks Copy, and pastes the finished command into the game console. It does not talk to the game — it only builds command strings for the clipboard.

Stack: Tauri v2 (Rust shell) + React 19 / TypeScript frontend, built with Vite.

Commands

npm install
npm run tauri dev        # run the full app (Rust + Vite HMR)
npm run tauri build      # release bundles (deb/AppImage on Linux, NSIS/MSI on Windows)
npm run dev              # frontend only in a browser — see "browser fallback" below
npm run build            # tsc typecheck + vite build (this is the only "test": there are no unit tests)
node scripts/fetch-data.mjs   # regenerate src/data/*.json from the upstream Cheat mod

There is no linter and no test suite. npm run build (which runs tsc) is the check to run before considering frontend work done. For Rust, cargo check / cargo clippy inside src-tauri/.

Windows cross-build from Linux uses cargo-xwin — see README.md "Building".

Architecture

Two halves that meet at a thin IPC boundary:

Rust shell (src-tauri/src/lib.rs) — main.rs just calls run(). This owns everything OS-level: the tray icon, the global hotkey (default ctrl+shift+k), and the overlay window (frameless, transparent, always-on-top, visible:false at startup — see tauri.conf.json). Key behaviors:

Closing the window hides it (prevent_close in on_window_event); the app only quits from the tray menu.
A second process launch is an IPC toggle (tauri_plugin_single_instance + --toggle arg) — this is the Wayland fallback for the unreliable global hotkey.
Settings persist via tauri_plugin_store in settings.json. The hotkey and start_hidden are read on the Rust side; set_hotkey re-registers and rolls back to the previous hotkey on failure so the overlay can never become unreachable.
Only four #[tauri::command]s are exposed: toggle_window, hide_window, set_hotkey, get_hotkey. Everything else (clipboard, store, autostart) uses Tauri plugins directly from JS.

Frontend (src/) — App.tsx is a tabbed overlay: Quick / Commands / Items / Perks / Buffs / Skills / Settings. All game data is vendored JSON in src/data/ and imported statically; the app is fully offline with no runtime fetches.

src/lib/tauri.ts — the only place that touches Tauri APIs. Every function has a browser fallback (guarded by inTauri), so npm run dev in a plain browser is usable for UI work: clipboard falls back to navigator.clipboard, the store to localStorage, and window/hotkey calls become no-ops. When adding native functionality, wrap it here, not in components.
src/lib/commands.ts — command-string builders and the token search (matches). Two command flavors exist and are built differently:
- devmode / vanilla (VanillaCommand): a {placeholder} template filled by buildFromTemplate. Requires the game launched with -devmode.
- cheatmod (ModCommand): built as name arg:value pairs by buildFromArgs. Requires the Nexus "Cheat" mod. flavor in Settings picks the user's preferred one; database tabs often emit both variants.
src/tabs/databases.tsx — Items/Perks/Buffs/Skills are all thin configs over the shared DatabaseTab component: each provides params and a build(entry, values) that returns labeled command variants. This is where the exact command syntax for each cheat type lives (e.g. cheat_add_item exact:… amount:… condition:… vs the devmode Lua #player.inventory:…). To change how a database command is emitted, edit the buildX functions here.
src/types.ts is the shared contract for all the JSON shapes and command types — read it first when touching data or command logic.

Data pipeline

src/data/*.json is generated, not hand-edited — except commands-vanilla.json and quick-cheats.json, which are hand-curated from community lists. scripts/fetch-data.mjs pulls CSV/txt dumps from the upstream pryans/kcd2-cheat repo and parses them:

a custom CSV dialect (backslash-escaped commas, quoted fields with literal newlines),
HTML-entity-encoded rich-text descriptions flattened to plain text,
the Cheat mod's docs.txt (BBCode) parsed into commands with args/examples,
command categories assigned by regex in CATEGORY_RULES.

Output is committed so builds stay offline. Re-run the script to refresh when the upstream mod updates. meta.json records the source, mod version, and fetch timestamp.