Python Block Breaker (Arkanoid 2D Game)

Python Block Breaker je kompletní vzdělávací 2D herní aplikace v jazyce Python postavená na moderní grafické knihovně Python Arcade (arcade). Hra je přímo inspirována legendárním retro hitem Arkanoid (žánr Brick Breaker).

Hráč ovládá pálku v dolní části obrazovky, pohybuje jí do stran pomocí kláves A/D nebo šipek a odráží míček směrem k mřížce zničitelných cihel v horní části obrazovky. Cílem hry je zničit všechny cihly bez toho, aby míček spadl pod pálku. Projekt slouží jako ideální výukový checkpoint pro zvládnutí objektově orientovaného programování (OOP), herní smyčky, 2D vektorové fyziky a kolizí.

---

🎯 Klíčová témata a výukové cíle

• Objektově orientované programování (OOP): Využití třídy BlockBreakerGame s děděním od základní třídy arcade.Window.
• Herní smyčka a životní cyklus: Práce s callback metodami setup(), on_draw(), on_update(), on_key_press() a on_key_release().
• Stavové řízení (State Machine): Přepínání herních režimů (STATE_MENU, STATE_PLAYING, STATE_GAME_OVER, STATE_WIN).
• Správa 2D sprajtů: Vytváření a manipulace s objekty arcade.SpriteSolidColor, arcade.SpriteCircle a jejich hromadná správa v optimalizovaném kontejneru arcade.SpriteList.
• 2D fyzika a detekce kolizí:
  • Pohyb míčku s vektory rychlostí (change_x, change_y).
  • Odrazy od mantinelů okna.
  • Dynamický úhlový odraz míčku od pálky na základě vzdálenosti od jejího středu.
  • Kolize míčku se seznamem cihel (arcade.check_for_collision_with_list).
• Uživatelské rozhraní (UI) a multimédia: Zobrazení skóre, počítadla životů a přehrávání zvukových efektů z vestavěných zdrojů Arcade (:resources:).

---

📐 Architektura Aplikace (UML Diagram)

classDiagram
    class arcade_Window {
        +clear() None
        +set_background_color(color) None
    }

    class BlockBreakerGame {
        +int current_state
        +int score
        +int lives
        +SpriteSolidColor paddle
        +SpriteList paddle_list
        +SpriteCircle ball
        +SpriteList ball_list
        +SpriteList brick_list
        +Sound sound_bounce
        +Sound sound_hit_brick
        +Sound sound_lose
        +__init__() None
        +setup() None
        +reset_ball() None
        +on_draw() None
        +on_update(float delta_time) None
        +on_key_press(int symbol, int modifiers) None
        +on_key_release(int symbol, int modifiers) None
    }

    class Paddle {
        +float width
        +float height
        +float center_x
        +float center_y
        +float change_x
    }

    class Ball {
        +float radius
        +float center_x
        +float center_y
        +float change_x
        +float change_y
    }

    class Brick {
        +float width
        +float height
        +float center_x
        +float center_y
        +Color color
    }

    arcade_Window <|-- BlockBreakerGame
    BlockBreakerGame *-- Paddle : contains
    BlockBreakerGame *-- Ball : contains
    BlockBreakerGame *-- Brick : manages in SpriteList

Loading

---

🧩 Struktura projektu

python-block-breaker/
├── docs/
│   ├── python-arcade-tahak.md        # Rychlý přehled a tahák pro knihovnu Arcade
│   └── python-block-breaker-spec.md  # Kompletní technická specifikace hry
├── main.py                           # Referenční plně funkční řešení s metodickými komentáři
├── main_students.py                  # Studentská verze s TODO úkoly a nápovědami
├── requirements.txt                  # Seznam externích závislostí (arcade)
├── LICENSE                           # GNU Affero General Public License v3 (AGPL-3.0)
└── README.md                         # Didaktický průvodce a dokumentace projektu

---

🚀 Jak spustit projekt

1. Instalace závislostí

Před prvním spuštěním nainstalujte potřebnou knihovnu arcade pomocí správce balíčků:

pip install -r requirements.txt

2. Spuštění referenčního řešení

Pro spuštění kompletní a plně odladěné verze hry:

python main.py

3. Práce na studentské verzi

Pro samostatné plnění úkolů otevřete soubor main_students.py a postupujte podle komentářů TODO 1 až TODO 7:

python main_students.py

---

🎯 Co student zvládne

1. Práci s 2D grafickou knihovnou: Pochopení rozdílu mezi synchronním kódem a smyčkou řízenou událostmi (Event Loop).
2. Implementaci herní fyziky: Výpočet vektorů rychlostí, mantinelů a úhlových odrazů.
3. Kolizní algoritmy: Práce s kolizemi typu objekt-objekt (check_for_collision) a objekt-seznam (check_for_collision_with_list).
4. Stavové automaty v praxi: Řízení průběhu aplikace pomocí jasně definovaných stavů (Menu, Hra, Game Over, Win).
5. Čistý a typovaný kód: Používání Type Hints a dodržování standardů PEP 8.

---

⚙️ Použité technologie a požadavky

• Python 3.10+
• Python Arcade (arcade>=2.6.0)
• Standardní knihovna Pythonu: modul typing

---

👤 Autor a Licencování

Autor: Jakub Březa (Vlk samotář) – VlkSamotar.cz | Informatika | Trading | Elektrotechnika

---

📜 Licence & Komerční využití

Tento projekt je šířen pod licencí GNU Affero General Public License v3 (AGPL-3.0) (viz přiložený soubor LICENSE).

Co to znamená?

• Pro studenty a samouky: Projekt můžete volně používat, studovat a upravovat pro své osobní účely.
• Pro lektory a vzdělávací organizace: Můžete projekt využít při výuce, ale pokud aplikaci (nebo její upravenou verzi) provozujete na síti/serveru či distribuujete, musíte zachovat zdrojový kód otevřený pod stejnou licencí AGPL-3.0 a uvést původního autora.

💼 Máte zájem o komerční využití bez omezení AGPL?

Pokud chcete tento interaktivní playground / aplikaci integrovat do své komerční (uzavřené) platformy, e-learningu nebo máte zájem o white-label řešení pro vaši školu, kontaktujte mě na VlkSamotar.cz pro sjednání komerční proprietární licence.

---

🧩 Třetí strany a závislosti

Tento projekt využívá standardní knihovnu Pythonu a knihovnu Python Arcade šířenou pod licencí MIT. Použití těchto knihoven je plně v souladu s licencí tohoto projektu.