🎮 Hangman Game (Wisielec) by SeveTo

🔗 🔴 Zobacz Demo na żywo / Live Demo (Kliknij tutaj) 🔗

🇺🇸 Read this README in English

Nowoczesna, w pełni responsywna iteracja klasycznej gry "Wisielec", stworzona przeze mnie w architekturze nakierowanej na obiektowość (OOP) w oparciu o czystego Vanilla JavaScripta (ES Modules). Gra oferuje przemyślany, autorski design i płynne animacje, dbając o jak najlepsze odczarowanie znanej nam szkolnej gry.

🌙 Dark Mode Showcase

Zwycięstwo (Win)	Porażka (Lose)

📸 Galeria i Screenshoty (Hi-Res)

Pełny podgląd interfejsu (Light & Dark):

Tryb Jasny (Light Mode)	Tryb Ciemny (Dark Mode)

⚡ Detale techniczne: Zadbałem o optymalizację obrazów podglądu, serwując je w formatach .gif (demo funkcjonalności) oraz .webp (statyczny Hi-Res). Pozwala to na zachowanie balansu między atrakcyjną prezentacją a szybkim czasem ładowania repozytorium.

🚀 Kluczowe funkcjonalności

• 🌓 Tryb Dark Mode – pełne wsparcie dla ciemnego motywu zmieniającego wizualny nastrój gry.
• 🔊 Interaktywne efekty dźwiękowe – informacja zwrotna audio przy każdym kroku (wygrana, błąd, przyciski).
• 📱 Responsive Web Design (RWD) – gra dopasowuje się do każdego urządzenia, od smartfonów po duże monitory.
• ⌨️ Obsługa klawiatury fizycznej – możesz grać tak, jak lubisz (myszką lub pisząc na klawiaturze).
• 🚀 System kategorii – łatwa rozbudowa bazy słów poprzez edycję jednego pliku JSON.

🛠️ Tech Stack & Narzędzia

Chciałem udowodnić, że solidne, piękne pod kątem designu aplikacje można bez problemu napisać nie używając kolosalnych frameworków:

Zewnętrzne biblioteki

Choć cała logika samej gry oparta jest na moim silniku napisanym w JavaScript, postanowiłem wykorzystać dwie małe, świetne biblioteki do wzbogacenia oprawy wizualnej gracza:

• Animate.css – aby wprowadzić świetne wejścia modali końcowych z gratulacjami i błędem, nie pisząc setek linii fizycznych klatek kluczowych.
• Canvas Confetti – aby odpowiednio hucznie "wystrzelić" konfetti poprzez Canvas na cały ekran przeglądarki, gdy użytkownik wpisze właściwe litery.

🎨 Autorski Design i Ręcznie rysowane Komponenty (Hand-drawn)

Wszystkie zasoby graficzne użyte w tym projekcie zostały wykonane przeze mnie. Zależało mi, by projekt nie bazował na tzw. stockowych gotowcach pobranych z darmowych banków zdjęć:

• Komponenty interfejsu (UI) zostały zaprojektowane oraz ostylowane całkowicie od podstaw tak, aby odzwierciedlały szkolny, ręczny blok rysunkowy (za pomocą nierównych ramek i czcionek pędzla).
• Rysunki samej "szubienicy" i wszystkich następujących po sobie partii przegrywającego "ludzika" (pliki .svg) narysowałem ręcznie.

🎵 Audio: Pozostałe w grze niesamowite i satysfakcjonujące efekty dźwiękowe – ze względu na otwarty charakter mojego projektu – pochodzą z darmowej bazy audialnej serwisu Pixabay Sound Effects.

✨ Dobre praktyki i Architektura, z których skorzystałem

Dołożyłem wszelkich starań, aby kod pisał się i rozwijał tak lekko jak to możliwe. Wcieliłem pod to następujące zagadnienia w oparciu o Clean Code:

• OOP (Obiektowość) oraz ES Modules – Gra rozbita jest na wzywane wzajemnie, odizolowane skrypty modułowe. Klasa Game.js kieruje całym cyklem, podczas gdy z boku pomagają mu bezobsługowo wstrzyknięci koledzy, np. AudioService.js (puszczający stwiedzenia audio bez nachodzenia w czasie) oraz WordService.js (szukający losowych tekstów z plików formatu .json).
• Zabezpieczenie przed atakami XSS (Data Sanitization) – Choć to gra, potraktowałem ją bardzo poważnie. Płynące do modali domeny ciągi "słów do zgadnięcia" czy okienka w całości są chronione z pomocą tworzenia bezpiecznych guzików poprzez natywne DOM API document.createElement() i zmienianie ich atrybutu .textContent — wystrzegając się używania innerHTML w newralgicznych tekstach mogących przenieść podatny, szkodliwy kod obcych znaków skryptowych.
• Debouncing na eventach klawiatury – Uciąłem całkowicie potencjalne, nieprzewidywalne zachowanie czy przerywanie asynchronicznych animacji gracza (np. za pomocą super prędkiego spamowania w fizyczną klawiaturę bez puszczania klawisza spacji). Program posiada mikro-chłodzenie po kliknięciu klawiszy, aby w stabilny sposób ukierunkować zdarzenia od strony "Event Loop" głównego interfejsu JavaScriptu .
• Odporność na błędy (Fallback) dla bazy .json – Zaimplementowałem asynchronicznego fetcha otoczonego solidnym blokiem try...catch. W przypadku gdyby ktoś z pobierających aplikację uruchomiłby "Wisielca" prosto kliknięciem w folder, na standardowym protokole plików dysku (file:///), blokujące zapytania ograniczenia CORS przeglądarek nie wycofają całej gry. Usługa automatycznie złapie odmowę dostępu i zaaplikuje awaryjną bazę słów i kategorii dla działania w trybie kompletnie "offline'owym", pozbawionym lokalnego silnika i serwera Live Server.

📈 Wydajność i Optymalizacja (Lighthouse 4x100)

Projekt został poddany rygorystycznym testom wydajnościowym i audytowi bezpieczeństwa. Udało się osiągnąć maksymalną punktację 100/100/100/100 w narzędziu Lighthouse (testowane w przeglądarce Microsoft Edge na serwerze lokalnym):

Note

Decyzja o czytelności: Choć Lighthouse sugeruje dodatkową minifikację plików CSS i JS, świadomie z niej zrezygnowałem w tym repozytorium. Priorytetem była dla mnie czytelność kodu dla osób przeglądających to portfolio. Mimo braku minifikacji, dzięki innym optymalizacjom (preloady, self-hosted fonts, async CSS), aplikacja działa błyskawicznie.

🚀 Jak uruchomić to samemu

1. Sklonuj repozytorium do siebie.
2. Mając otwarty folder środowiskiem np. VS Code - użyj rozszerzenia tj. Live Server i ciesz się nieograniczonym dostępem do odczytania bogatej biblioteki wyrazów i kategorii z .json.
3. ... A jeżeli nie dysponujesz Live Serverem i jesteś po prostu osobą testującą klikając plik, gra, dzięki wymienionemu powyżej mechanizmowi Fallback, uruchomi awaryjną listę haseł i poinformuje Cię o awaryjnym trybie bez wywalania ekranu!

Ciesz się moją grą!