From 735d8766a22c39ad59090d827ad5361359471407 Mon Sep 17 00:00:00 2001 From: funman300 Date: Tue, 28 Apr 2026 22:37:07 +0000 Subject: [PATCH] docs(engine): add missing doc comments on layout, ProgressPlugin; fix audio format in ARCHITECTURE.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add field-level doc comments to Layout::card_size and Layout::pile_positions - Add struct-level doc comment to ProgressPlugin - Fix ARCHITECTURE.md Section 14: .ogg → .wav throughout Co-Authored-By: Claude Sonnet 4.6 --- ARCHITECTURE.md | 14 +++++++------- solitaire_engine/src/layout.rs | 11 +++++++++-- solitaire_engine/src/progress_plugin.rs | 5 +++++ 3 files changed, 21 insertions(+), 9 deletions(-) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index de61390..d6698ae 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -851,16 +851,16 @@ Levels 11+: level = 10 + floor((total_xp - 5000) / 1000) ## 14. Audio System -Audio uses `bevy_kira_audio`. All sound files are `.ogg` (good compression, cross-platform, royalty-free). +Audio uses `bevy_kira_audio`. All sound files are `.wav`. | File | Trigger | |---|---| -| `card_deal.ogg` | New game deal animation | -| `card_flip.ogg` | Card flips face-up | -| `card_place.ogg` | Valid card placement | -| `card_invalid.ogg` | Invalid move attempt | -| `win_fanfare.ogg` | Game won | -| `ambient_loop.ogg` | Looping background music (restarts seamlessly) | +| `card_deal.wav` | New game deal animation | +| `card_flip.wav` | Card flips face-up | +| `card_place.wav` | Valid card placement | +| `card_invalid.wav` | Invalid move attempt | +| `win_fanfare.wav` | Game won | +| `ambient_loop.wav` | Looping background music (restarts seamlessly) | Volume is controlled by two independent sliders in Settings (`sfx_volume`, `music_volume`), each stored in `Settings` and applied as `bevy_kira_audio` channel volumes. diff --git a/solitaire_engine/src/layout.rs b/solitaire_engine/src/layout.rs index ed3b90d..787e7c9 100644 --- a/solitaire_engine/src/layout.rs +++ b/solitaire_engine/src/layout.rs @@ -27,9 +27,16 @@ pub const TABLE_COLOUR: [f32; 3] = [0.059, 0.322, 0.196]; /// Computed board layout for a given window size. #[derive(Debug, Clone)] pub struct Layout { - /// Width/height of a single card, in world units. + /// Width and height of a single card, in world units (Bevy 2D world-space). + /// + /// `x` is the card width; `y` is the card height (always `x * 1.4`). + /// All pile positions and fan offsets are derived from this value. pub card_size: Vec2, - /// Centre position of each pile, in world coordinates. + /// Centre position of each pile, in 2D world coordinates. + /// + /// World origin `(0, 0)` is the window centre; `+x` is right, `+y` is up. + /// Every `PileType` (Stock, Waste, four Foundations, seven Tableaux) has an + /// entry. The map always contains exactly 13 entries after `compute_layout`. pub pile_positions: HashMap, } diff --git a/solitaire_engine/src/progress_plugin.rs b/solitaire_engine/src/progress_plugin.rs index 87bbfb6..7f0c34f 100644 --- a/solitaire_engine/src/progress_plugin.rs +++ b/solitaire_engine/src/progress_plugin.rs @@ -37,6 +37,11 @@ pub struct LevelUpEvent { #[derive(SystemSet, Debug, Clone, PartialEq, Eq, Hash)] pub struct ProgressUpdate; +/// Bevy plugin that awards XP on `GameWonEvent`, persists `PlayerProgress`, +/// and emits `LevelUpEvent` whenever a win crosses a level boundary. +/// +/// Use `ProgressPlugin::default()` in the main app (reads/writes the platform +/// data directory) and `ProgressPlugin::headless()` in tests (no I/O). pub struct ProgressPlugin { pub storage_path: Option, }