From d8c70341f4ae56343907e3e5a7fcdeeb1a970090 Mon Sep 17 00:00:00 2001 From: funman300 Date: Sat, 2 May 2026 00:56:24 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20refresh=20README=20for=20v0.11.0=20?= =?UTF-8?q?=E2=80=94=20card=20themes,=20HUD=20overhaul,=20drag=20feel?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The README hadn't been touched since before the card-theme system landed and was missing every UX feel improvement from v0.11.0. Anyone discovering the repo on the GitHub release page would have seen pre-theme copy. Features list now covers card themes (bundled default + user zip-installable), the modern HUD (reserved band + action-bar auto-fade), and the four drag-feel improvements (drop highlights, drop shadows, stock count badge, unlocked foundations). Controls table fixes three real discrepancies: Undo is U not Z/Ctrl+Z (the README inverted the bindings), Help is F1 not H, and Z actually toggles Zen mode. Adds the previously undocumented Tab / Shift+Tab focus cycle, Enter activation, F11 fullscreen, double- click to auto-move, and the G forfeit shortcut. Notes that every action is also a visible UI button so the keyboard list is optional-accelerator only — matches the project's UI-first rule. Adds a small Card Themes section explaining how to install a theme (drop a directory or zip-import via Settings → Cosmetic) without diving into SVG technicals. Test count updated to 982 to reflect v0.11.0 baseline. Co-Authored-By: Claude Opus 4.7 (1M context) --- README.md | 75 ++++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 55 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 27b7c7a..b45d438 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,35 @@ # Solitaire Quest -A cross-platform Klondike Solitaire game written in Rust, featuring a full progression system with XP, levels, achievements, daily challenges, and optional self-hosted sync so your stats follow you across machines. +A cross-platform Klondike Solitaire game written in Rust, with a card-theme +system, full progression (XP / levels / achievements / daily challenges), and +optional self-hosted sync so your stats follow you across machines. ## Features -- **Klondike Solitaire** — Draw One and Draw Three modes +- **Klondike Solitaire** — Draw One and Draw Three modes; foundations are + unlocked (any Ace lands in any empty slot, the slot then claims that suit) +- **Card themes** — bundled hayeah/playing-cards-assets default plus + user-installable themes (drop a directory under the data dir or import a + zip from Settings → Cosmetic) +- **Modern HUD** — reserved top band keeps cards from crowding the score + readout; the action bar auto-fades when the cursor leaves it so it can't + compete with the play surface +- **Drag feel** — every legal drop target is highlighted in green during + drag; cards cast a soft drop shadow that lifts when picked up; the stock + pile shows a remaining-count chip so you can see how close you are to a + recycle +- **Keyboard navigation** — Tab cycles focus through buttons, arrow keys + move within picker rows, Enter activates; works across every modal and + the HUD action bar - **Progression** — XP, levels, unlockable card backs and backgrounds - **18 Achievements** — including secret ones -- **Daily Challenge** — server-seeded so every player worldwide gets the same deal +- **Daily Challenge** — server-seeded so every player worldwide gets the + same deal - **Leaderboard** — opt-in, powered by your own self-hosted server - **Special Modes** (unlocked at level 5): Zen, Time Attack, Challenge - **Sync** — pull/push stats across devices via a self-hosted server -- **Color-blind mode** — blue tint on red-suit cards +- **Color-blind mode** — blue tint on red-suit cards alongside the suit + glyph ## Building @@ -32,46 +50,63 @@ cargo build -p solitaire_app --release ## Controls +Every action also has a visible UI button — keyboard shortcuts are optional +accelerators. + | Key | Action | |---|---| | Left click / drag | Move cards | +| Double click | Auto-move card to its best legal destination | | Right click | Highlight legal moves for a card | | Space / D | Draw from stock | -| Z / Ctrl+Z | Undo | +| U | Undo | +| H | Hint (highlight a legal move) | | N | New game | -| S | Stats overlay | -| A | Achievements overlay | -| P | Profile overlay | -| O | Settings | -| L | Leaderboard | -| H | Help / controls | -| Enter | Auto-complete (when badge is lit) | -| Escape | Pause / clear selection | -| Arrow keys | Navigate card selection | +| Z | Zen mode | +| G | Forfeit (during pause) | +| Tab / Shift+Tab | Cycle keyboard focus | +| Enter | Activate focused button / auto-complete (when badge is lit) | +| Esc | Pause / dismiss modal | +| F1 | Help / controls | +| F11 | Toggle fullscreen | +| S / A / P / O / L / M | Stats / Achievements / Profile / Settings / Leaderboard / Menu | + +## Card themes + +The default theme ships embedded in the binary, so the game runs +self-contained with no external assets. To install another theme, drop a +directory containing a `theme.ron` manifest plus 53 SVG files (52 faces + +1 back) under the platform data dir's `themes/` folder, or import a zip +from **Settings → Cosmetic**. The picker chip lights up the moment a new +theme is registered. Themes are SVG-based, so they rasterise cleanly at +whatever resolution the window happens to be. ## Sync Server (optional) -To sync stats across machines, run the self-hosted server. See [README_SERVER.md](README_SERVER.md) for setup instructions. +To sync stats across machines, run the self-hosted server. See +[README_SERVER.md](README_SERVER.md) for setup instructions. -Once the server is running, open **Settings → Sync Backend**, enter the server URL and your username, and register an account from within the game. +Once the server is running, open **Settings → Sync Backend**, enter the +server URL and your username, and register an account from within the +game. ## Running Tests ```bash -# All tests +# All tests (982 passing as of v0.11.0) cargo test --workspace # Just game logic (no display required) cargo test -p solitaire_core -p solitaire_sync -p solitaire_data -p solitaire_server # Lint -cargo clippy --workspace -- -D warnings +cargo clippy --workspace --all-targets -- -D warnings ``` ## Credits -Built on [Bevy](https://bevyengine.org/) and the wider Rust ecosystem (Tokio, -Axum, sqlx, Serde, kira, and many more). Card faces come from +Built on [Bevy](https://bevyengine.org/) and the wider Rust ecosystem +(Tokio, Axum, sqlx, Serde, kira, and many more). Card faces come from [hayeah/playing-cards-assets](https://github.com/hayeah/playing-cards-assets) (MIT, derived from the public-domain `vector-playing-cards` library); the default card back is original work; the UI font is FiraMono-Medium (OFL).