Author Erik Vaněk
Language C++ 20, CMake 4.0
Hangman is a console-based implementation of the classic word guessing game. This project is designed as a demonstration of multithreaded programming in C++ 20.
The game separates input handling, game logic, and rendering into separate threads that communicate via thread-safe queues.
Firstly I started the project with the goal of just building the game alone that works - that can be seen in the early commits.
Once the game logic was functional, I refactored the code and separated it into different classes and files - hangman, word_repository, and view.
Then I dived into the multithreading aspect of the project. I created separate threads for input handling, game logic, and rendering.
To ensure communication between these threads, I implemented a thread-safe queue safe_queue<T> - this ensures that data can be safely passed between threads without race conditions.
The final step of the project was testing and implementation of unit tests to ensure the correctness of the game logic.
For that, I used Catch2 testing framework, which is allowed in the project assignment. Simultaneously, I manually tested the game with my friend too.
The code is detailed with comments explaining the purpose of each class and method.
-
~/- root directort with main, cmakelists and words.txt -
game/- contains the core game logic and visualizationhangman.h/cpp- game controller class. Maintains state (secret word, mistake count)word_repository.h/cpp- loads words from config fileview.h/cpp- static class for rendering UI and ASCII artgame_state.h- struct for storing current game stategame_thread.h- functions for the game logic thread
-
thread/- contains threads logicsafe_queue.h- thread-safe queue implementationinput_thread.h- functions for the inputoutput_thread.h- functions for the output
-
test/**: Unit tests (using the Catch2 framework).
hangman- the main game controllerinit_game()- inits the game and picks a random word and resets countersprocess_guess(string)evaluates the guess (letter or full word) and returns updatedgame_stateupdate_revealed_state(const std::string &guess)- updates the revealed letters based on the guess
word_repository:load_words_from_file(const std::string &file_path)- loads words from a specified file path into memoryget_random_word(size_t length)- retrieves a random word of specified (or random) length from the loaded words in memory
view:draw_hangman(int mistakes)- draws the ASCII art hangman stage based on the number of mistakesdisplay_word_state(const std::string &state)- displays the current revealed state of the word
game_state- struct that holds the current state of the game (revealed letters, mistakes, guessed letters, win/loss status)
- Liner scan of guessing letters
- when a letter is guessed, a linear scan of the secret word is performed O(N) - N is word length
- Random word selection
- upon game start a pseudo-rng index is selected
- if a specific word length is requested, the words are filtered O(N) - N is the total number of words
- the word at the selected index is chosen as the secret word
- Input normalization
- input strings are iteratively converted to uppercase and stripped of non-printable characters
Synchronization is ensured by using the safe_queue<T>, which uses mutex and condition_variable to safely pass data between threads.
The application is divided into three main running threads managed in main.cpp
-
game_thread- contains the instance of the
hangman - gets inputs from the
input_queue - processes guess calls
game_logic.process_guess() - generates a new
game_stateand pushes it into therender_queue
- contains the instance of the
-
input_thread- responsible for reading user input from console
- normalizes input to uppercase
- pushes input data into the
input_queue - lets user exit the game by using the
0command
-
output_thread- uses current game states from the
render_queue - uses the
viewclass to render states to console - hangman art, mistakes, guessed letters, etc... - uses ANSI escape codes for colored output.
- uses current game states from the
The project includes unit tests for the hangman and word_repository classes, located in the test/ directory.
Furthermore, the program was thoroughly tested manually, by me and my friend, to ensure correct multithreaded behavior and game logic. By testing various input lengths, invalid characters, win/loss conditions, and edge cases.
- C++20 compatible compiler (e.g., g++ 11+, clang 12+
- CMake 4.0+
- terminal/console with ANSI escape code support
- prepared words for the game in
words.txt(one word per line)
- Open the projects root directory
- Ensure the words.txt file is present and is filled with words (one per line)
- Create build folder, navigate into it, and run CMake
mkdir build cd build cmake .. cmake --build .
- Run the generated
HangManexecutable./HangMan
The words for the game are loaded from the words.txt file located in the root directory.
You can modify this file to add or remove words as desired - always one word per line.
The app has included --help command line argument (CLA) that displays usage information.
Additionally, user can append a CLA -s or --size followed by a number to set the word length for the game.
- after launching press
ENTERto start a new game - your goal is to guess a hidden word chosen randomly from the dictionary in
words.txt - you have 10 attempts to guess - one letter at a time or attempt to guess the entire word
- to submit a guess press
ENTER - input is case-insensitive - all letters are treated as uppercase
- to exit the game at any time, you can enter
0or pressCtrl+C