From 45b50857b177d8befd5b21ce37100649d2a581e8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jaroslav=20Bene=C5=A1?= Date: Sat, 8 Aug 2026 18:35:57 +0200 Subject: [PATCH] The overlay's working notes, out of the working tree They were an untracked CLAUDE.md sitting beside the code -- never committed, so nothing had to be removed from the history. It only ever existed on one machine, which is the opposite of documentation. Co-Authored-By: Claude Opus 5 (1M context) --- Home.md | 23 ++++++++++++- Working-notes.md | 87 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 109 insertions(+), 1 deletion(-) create mode 100644 Working-notes.md diff --git a/Home.md b/Home.md index a3e8842..07f52fb 100644 --- a/Home.md +++ b/Home.md @@ -1 +1,22 @@ -Placeholder. Replaced by the first push. \ No newline at end of file +# Kingdom Cheat: Deliverance II + +A desktop **overlay** for *Kingdom Come: Deliverance II* — a searchable database +of console commands, items, perks, buffs and skills. Fill in the parameters, +click **Copy**, paste 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) with a **React 19 / TypeScript** frontend, built +with Vite. + +Source: [`Houmeres/Kingdom-Cheat-Deliverance-2`](https://git.houmeres.sk/Houmeres/Kingdom-Cheat-Deliverance-2). + +| Page | What it is | +|---|---| +| [Working-notes](Working-notes) | The rules, the repository layout, and how the data files and command builders fit together. | + +--- + +This page was an untracked `CLAUDE.md` in the working tree. Unlike the other +repositories in this org, **KCD2's history was not rewritten** — the file was +never committed, so there was nothing in the history to remove. diff --git a/Working-notes.md b/Working-notes.md new file mode 100644 index 0000000..23563a4 --- /dev/null +++ b/Working-notes.md @@ -0,0 +1,87 @@ +# 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 + +```sh +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.