version 1.0.0

.mailmap

@@ -1,5 +1,6 @@
 Andrei Kurochkin <end41r@gmx.de> <andi.kurochkin@gmail.com>
 Andrei Kurochkin <end41r@gmx.de> <82461251+end41r@users.noreply.github.com>
+Andrei Kurochkin <end41r@gmx.de>
 Konrad Kortes <konrad.kortes@gmail.com> <konrad@MacBook-Pro-von-Konrad.local>
 Konrad Kortes <konrad.kortes@gmail.com> <konrad@MacBookPro.fritz.box>
 Konrad Kortes <konrad.kortes@gmail.com> <konrad@MacBook-Pro-von-Konrad.fritz.box>

Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "wizard"
-version = "0.1.0"
-edition = "2021"
+version = "1.0.0"
+edition = "2024"
 
 [dependencies]
 iced = { version = "0.14", features = ["image", "tokio"] }
@@ -17,6 +17,7 @@ derive_more = { version = "2.1.1", features = ["deref", "deref_mut"] }
 rand = "0.9.2"
 strum = "0.27"
 strum_macros = "0.27"
+rodio = "0.21.1"
 
 [features]
 wiz_debug = []

DOCUMENTATION.md

@@ -0,0 +1,177 @@
+# DOCUMENTATION
+
+## Overview
+
+A digital implementation of the classic [Wizard card game](https://en.wikipedia.org/wiki/Wizard_(card_game)), built in Rust using the Iced UI framework for the client and Axum for the server, designed for playing in a local network.
+
+---
+
+## Building and Running
+
+### Prerequisites
+
+- **Cargo, Rust** toolchain (`edition=2024`, the project enforces `1.90.0` via `rust-toolchain.toml`)
+- **On Linux:** the `alsa` library for audio must be installed (e.g. `sudo apt install libasound2-dev` on Ubuntu)
+
+### Clone and Run
+
+```sh
+git clone https://github.com/end41r/wizard.git
+cd wizard
+cargo build
+cargo run
+```
+
+### Cross-Compilation with `build.sh`
+
+Primarily for WSL > Windows for better testing experience:
+
+```sh
+./build.sh -t windows    # Windows release build
+./build.sh -t linux      # Linux release build
+./build.sh -t windows -f # Windows release build with debug features (wiz_debug)
+```
+
+The script compiles a release binary and copies both the executable and the `assets/` folder to a directory specified in `DEST_PATH`.
+
+### Running Tests
+
+```sh
+cargo test
+```
+
+Unit are located in `src/gamelogic/game.rs` (UI testing was done differently).
+
+---
+
+## Implemented Features and How to Discover Them
+
+### Main Menu
+
+When the application starts, the main menu is displayed with four buttons:
+
+| Button | Action |
+| -------- | -------- |
+| **Host** | Opens the host menu to create a new game lobby |
+| **Beitreten** | Opens the join menu to connect to an existing lobby |
+| **Optionen** | Opens audio settings |
+| **Spiel Verlassen** | Exits the application |
+
+### Hosting a Game
+
+1. Click **Host** in the main menu.
+2. Enter your player name.
+3. Select the player count (3–6 players).
+4. Click **Lobby Erstellen** — this starts the WebSocket server on port `3000` and puts you in the lobby.
+5. Share your IP address (shown in the lobby) with the other players.
+
+### Joining a Game
+
+1. Click **Beitreten** in the main menu.
+2. Enter your player name and the host's IP address.
+3. Click **Verbinden** to join the lobby.
+
+### Lobby
+
+- All connected players are listed with a **Bereit | Nicht Bereit** toggle.
+- The lobby includes a chat where players can send messages.
+- The game starts when all players are ready and the host presses **Starten**.
+
+### Rules
+
+The game follows the official Wizard card game rules. A full in-game rules screen is accessible via the **Spielregeln** button in **Optionen**. In brief:
+
+#### Gameplay UI
+
+- **Card hand:** Cards that are displayed at the bottom, with a right click you can also see which are playable.
+- **Game table:** Shows other players' avatars, the current trick's cards in the middle, if you click the trick's cards you can toggle the view of all played cards in the trick, by just hovering you can temporarily see the played cards in the trick.
+- **Scoreboard:** Displayed on the side, shows each player's current score, bid, and tricks won. The scoreboard also provides trump-suit selection buttons when the dealer must set trump.
+- **Avatars:** Each player has an animated avatar (Elf, Knight, Mage, or Witch) with idle and casting animations. Casting is triggered when a player plays acard. Each avatar type has unique sound effects upon clicking the avatar.
+- **Shards:** Float around the avatar of each player, indicating the amount of cards left in their hand.
+
+### Audio
+
+- **Background music** plays on the menu, in the lobby, and during gameplay (different tracks for each).
+- **Sound effects** for: button clicks, card hover, card shuffle, card deal, card play, card error, shard play, avatar-specific casting and click sounds, and game over.
+- **Volume control:** Music and SFX volume can be adjusted via sliders in the **Optionen** menu.
+
+### Easter Egg
+
+If the host enters the name `wizard_master`, the game launches in a **debug gameplay view** — a text-based, scrollable interface showing all game states (round, trump, bids, hand, tricks, scores, log) with minimal styling. This is located in `src/client/views/debug_gameplay.rs`.
+
+### Debug Build Feature
+
+Compiling with the `wiz_debug` Cargo feature (`cargo run --features wiz_debug`) enables:
+
+- The Windows console window in release builds (for logging output).
+- Better testing conditions (you can start with 1 player without waiting for everybody to get ready).
+
+### Cross-Platform
+
+The application runs on **Linux**, **Windows**, and **macOS**.
+
+---
+
+## Architecture
+
+### Client ↔ Server Model
+
+- `src/server.rs`: An Axum + Tokio WebSocket server. Manages player connections, lobby state, game state, and event broadcasting. Binds to `0.0.0.0:3000`.
+- `src/client/`: An Iced GUI application. Handles user input, animations, rendering, audio playback, and communicates with the server via WebSockets.
+
+### Core Modules
+
+- `src/main.rs` : Entry point; launches the Iced client
+- `src/api.rs` : Shared types, protocol messages (`C`, `S`, `B`), card/suit/value definitions, avatar types, lobby/player structs
+- `src/server.rs` : Axum WebSocket server, game event dispatching, lobby management
+- `src/gamelogic/` : Core game logic — `Game` (overall game flow) and `Round` (per-round state, bidding, trick resolution, scoring)
+- `src/client/mod.rs` : Client application state (`App`), message enum, initialization
+- `src/client/update.rs` : Message handling and state transitions
+- `src/client/ws.rs` : WebSocket connection management
+- `src/client/audio.rs` : Music and SFX playback via `rodio`
+- `src/client/views/` : UI views: main menu, host menu, join menu, options, lobby, rules, debug gameplay
+- `src/gameplay_ui/` : Game-table UI: hand display, card rendering, avatars, scoreboard, table layout
+- `src/animation.rs` : Animation framework with easing functions (basic, auto-reversing, circular animations)
+- `src/ui_element_traits.rs` : Shared traits for UI elements (Viewable, Animated, Resizable, etc.)
+
+### Main Dependencies
+
+- `iced` : UI framework (with image and tokio features)
+- `axum` : Web server framework with WebSocket support
+- `tokio` : Async runtime
+- `tokio-tungstenite` : WebSocket client implementation
+- `serde` / `serde_json` : Serialization and deserialization of protocol messages
+- `rodio` : Audio playback (music and sound effects)
+
+---
+
+## Testing Method
+
+### Approach
+
+The project uses Unit tests for the core game logic module (`src/gamelogic/game.rs`). This is the only module we could write tests for.
+
+### UI tests
+
+- UI testing was done manually by running the application and verifying that all features work as intended through hours of playing together / alone, because iced doesnt provide a nice way to test it's elements.
+
+---
+
+## AI / LLM Usage
+
+- **Easing functions** (`src/animation.rs`): Claude.ai generated the mathematical logic for easing functions (`ease_in_cubic`, `ease_out_cubic`, `ease_in_out_cubic`, `ease_in_sine`, `ease_out_sine`, `ease_in_out_sine`, `ease_out_elastic`, `ease_out_bounce`).
+- **Animation macros** (`src/animation.rs`): Claude.ai helped to learn how to write Rust macros and partially generated the `impl_animation_common!` macro and trait bound patterns.
+- **Scoreboard functions** (`src/gameplay_ui/scoreboard.rs`): AI helped to write the `sorted_player_order_by_score` function and the scoreboard view placement logic.
+- **Pixel art rendering** (`src/gameplay_ui/table/avatar.rs`): Claude helped to learn how to use `filter_method` to achieve non-blurred pixel art scaling.
+- **Hand generics** (`src/gameplay_ui/hand/mod.rs`): Claude.ai suggested passing a union type for generic hand card handling and helped to learn `Vec::contains` usage.
+- **Server WebSocket handler** (`src/server.rs`): Claude Opus helped implement the WebSocket connection handler.
+
+- **Array filtering** (`src/client/mod.rs`): Gemini helped to learn how to pass an array into a function and filter it.
+
+### AI-Generated Images
+
+The following image assets were created with AI assistance:
+
+- `background_forall.png`, `ingame_background.png`, `menu_container.png`
+- `wizard_lobby_menu.png`, `wizard_main_menu*.png`
+- `button1.png`, `Menu_Button.png`

README.md

@@ -1,30 +1,37 @@
 # wizard
-A Wizard Card game ( https://en.wikipedia.org/wiki/Wizard_(card_game) ) based on the Iced UI Framework to play in a local network with friends
 
+A Wizard Card game (<https://en.wikipedia.org/wiki/Wizard_(card_game)>) based on the Iced UI Framework to play in a local network with friends
+
+## To get the dependencies run
 
-## To get the dependencies run 
 `cargo build`
 
 ## Building for windows
+
 Uncomment a line at the top of main to remove the stdout terminal for a better experience
 
 ## Running
+
 `cargo run`
 
 ## Constraints
+
 Please refer to REQUIREMENTS.md
 
 We also have a pr check for clippy and fmt, so if it fails, please use
+
 - `cargo fmt` to fix formatting (automatically)
 - `cargo clippy` to check for the warnings (most of them will be gone if you use `cargo clippy --fix --bin "wizard"` (commit your changes beforehand))
 - If you really trust clippy, you can also do `cargo clippy --fix --bin "wizard" --allow-dirty`, but its better not to use it :)
 
 ### To run in debug mode with the wiz_debug feature enabled, run
+
 `cargo run --features wiz_debug`
 This will allow you to start the game with 1 player.
 
 ### build.sh usage
+
 - Allows building release executable files for windows/linux/mac with `./build.sh -t <target>`, also allows to build with a `wiz_debug` feature flag with `./build.sh -t <target> -f`
 - To build you would need to install targets first
 - To correctly copy the assets, you would need to run the script from the root of the project
-- The script copies the needed files as a release in your specified folder (in `DEST_PATH`)
+- The script copies the needed files as a release in your specified folder (in `DEST_PATH`)

REQUIREMENTS.md

@@ -1,12 +1,14 @@
 # Rust SEP Winter Term 25/26 – Final Project
 
 ## Requirements
+
 **Requirements written in bold are mandatory but not sufficient to pass.**  
 Other requirements should be fulfilled for a 1.0, but are also not sufficient.
 
 ---
 
 ## Git
+
 - [ ] **(G1) The submitted project is a Git repository.**
 - [ ] **(G2) The main branch contains the final project.**
 - [ ] **(G3) Collaborative development was continuously done via Git (commit history from December to February).**
@@ -21,7 +23,8 @@ Other requirements should be fulfilled for a 1.0, but are also not sufficient.
 ---
 
 ## Code
-- [ ] **(C1) The project must be compilable with rustc stable 1.85.0 (edition=2024).** 
+
+- [ ] **(C1) The project must be compilable with rustc stable 1.85.0 (edition=2024).**
 - [ ] **(C2) The project is executable.**
 - If the project is runnable via `cargo run`, it’s fine.  
 - If depending on non–crates.io dependencies, a devcontainer must include all required components.  
@@ -40,6 +43,7 @@ Other requirements should be fulfilled for a 1.0, but are also not sufficient.
 ---
 
 ## Functional
+
 - [ ] **(F1) The project was outlined in the pitch presentation.**
 - [ ] **(F2) The final submission resembles the pitched project.**
 - [ ] **(F3) The project must allow user interaction (usable without writing code).**
@@ -48,10 +52,11 @@ Other requirements should be fulfilled for a 1.0, but are also not sufficient.
 ---
 
 ## Documentation
+
 - [ ] **(D1) The documentation contains all steps needed to run the project.**
 - [ ] **(D2) The documentation lists all implemented features and how to discover them.**
 - [ ] **(D3) The logbook is submitted as a separate PDF on Moodle.**
 - [ ] **(D4) IFI Rule: State all used AI/LLMs and their purpose.**
 
 - [ ] (D5) The documentation contains proof of any requirement not proven by code or repo.  
-- [ ] (D6) The documentation describes and justifies the testing method.
+- [ ] (D6) The documentation describes and justifies the testing method.

build.sh

@@ -4,6 +4,7 @@ TARGET="linux"
 DEST_PATH="/mnt/c/Users/capos/Downloads"
 BUILD_TYPE="release"
 FEATURES=""
+EXE_EXT=""
 
 while getopts "t:fh" opt; do
     case $opt in
@@ -35,11 +36,9 @@ case $TARGET in
         ;;
     linux)
         TARGET_NAME="x86_64-unknown-linux-gnu"
-        EXE_EXT=""
         ;;
     macos)
         TARGET_NAME="aarch64-apple-darwin"
-        EXE_EXT=""
         ;;
     *)
         echo "Unknown target: $TARGET"

rust-toolchain.toml

@@ -0,0 +1,4 @@
+[toolchain]
+channel = "1.90.0"
+components = ["rustfmt", "clippy"]
+profile = "minimal"