python-arcade-oo/README.md

# OOP w Pythonie przez bibliotekę arcade — kurs 5-dniowy

Kurs dla osoby, która dobrze zna proceduralnego Pythona (pętle, funkcje, listy,
słowniki, algorytmy), ale nie pisała jeszcze klas. Przez pięć dni budujemy gry
w bibliotece [arcade](https://api.arcade.academy/) i przy okazji poznajemy
obiektowość: klasy, konstruktory, dziedziczenie, nadpisywanie metod, `property`.

Uwaga: kurs korzysta z **arcade 3.x** (zweryfikowano na 3.3.3). API 3.x różni się
od starych tutoriali z wersji 2.x — patrz sekcja „Pułapki API” na dole.

## Setup

```bash
# 1. Wirtualne środowisko (w katalogu projektu)
python3 -m venv .venv

# 2. Aktywacja
source .venv/bin/activate        # Linux / macOS
# .venv\Scripts\activate         # Windows (PowerShell / cmd)

# 3. Instalacja zależności
pip install -r requirements.txt

# 4. Sprawdzenie, czy działa
python -c "import arcade; print(arcade.VERSION)"
python dzien1/01_okno.py
```

Jeśli po `python dzien1/01_okno.py` otworzy się okno z napisem — środowisko jest
gotowe. Zamykamy okno krzyżykiem albo `Esc` (tam, gdzie jest obsłużony).

## Plan dni

| Katalog                  | Dzień | Temat                                             | Co ćwiczymy z OOP                                            |
| ------------------------ | ----- | ------------------------------------------------- | ------------------------------------------------------------ |
| `dzien1/`                | 1     | Pierwsze okno, rysowanie, ruch sprite'a           | klasa, `__init__`, `super()`, dziedziczenie po `arcade.Window`, nadpisywanie metod |
| `dzien2/`                | 2     | Zbieranie monet + własna hierarchia wrogów        | klasa bazowa i klasy pochodne, nadpisywanie `update()`, polimorfizm |
| `dzien3_4_platformowka/` | 3–4   | Platformówka wg oficjalnego tutoriala             | kompozycja obiektów (silnik fizyki, kamera, sceny), `property` z walidacją |
| `dzien5_projekt/`        | 5     | Własna gra od zera                                | projektowanie klas, podział na pliki, `arcade.View` jako stany gry |
| `assets/`                | —     | Grafika i dźwięki (do pobrania samodzielnie)      | —                                                            |

## Zasady pracy

1. **Uzupełniaj `TODO`.** Każdy plik startowy *działa* od razu — uruchom go
   najpierw bez zmian, zobacz co robi, dopiero potem szukaj `TODO:` i dopisuj kod.
2. **Uruchamiaj często.** Po każdej małej zmianie (5–15 linii) odpal program.
   Łatwiej znaleźć błąd w pięciu nowych liniach niż w stu.
3. **Commit po każdym działającym kroku.** Nie po każdym dniu — po każdym
   momencie, w którym gra znowu się uruchamia:
   ```bash
   git add -A
   git commit -m "dzien2: klasa Enemy odbija się od krawędzi"
   ```
   Dzięki temu zawsze można wrócić do ostatniej wersji, która działała.
4. **Czytaj komunikaty błędów od dołu.** Ostatnia linia traceback mówi *co* się
   stało, linie wyżej mówią *gdzie*.
5. **Nie kopiuj kodu, którego nie rozumiesz.** Jeśli coś w przykładzie jest
   niejasne — zmień to i zobacz, co się zepsuje. To najszybszy sposób nauki.

## Materiały

- Primer (szybkie wprowadzenie do arcade): <https://realpython.com/arcade-python-game-framework/>
- Kurs „Learn Arcade” (długi, po angielsku, z zadaniami): <https://learn.arcade.academy/>
- Tutorial platformówki (podstawa dni 3–4): <https://api.arcade.academy/en/latest/tutorials/platform_tutorial/index.html>
- Przykłady kodu (kopalnia gotowych rozwiązań): <https://api.arcade.academy/en/latest/example_code/index.html>
- Darmowe assety (grafika, dźwięki): <https://kenney.nl/assets>

## Pułapki API — arcade 3.x kontra stare tutoriale

Duża część poradników w internecie opisuje arcade 2.x. Najczęstsze różnice:

| Stare (2.x)                            | Aktualne (3.x)                                              |
| -------------------------------------- | ----------------------------------------------------------- |
| `arcade.start_render()` w `on_draw`     | `self.clear()`                                              |
| `sprite_list.on_update(delta_time)`     | `sprite_list.update(delta_time)` — `SpriteList` **nie ma** `on_update` |
| `def update(self):` w klasie sprite'a   | `def update(self, delta_time=1/60, *args, **kwargs):`       |
| `arcade.draw_rectangle_filled(...)`     | `arcade.draw_lrbt_rectangle_filled(...)` lub `draw_lbwh_rectangle_filled(...)` |
| `arcade.set_background_color(...)`      | `self.background_color = ...` (atrybut okna / widoku)       |
| `arcade.Camera(...)`                    | `arcade.Camera2D(...)`                                      |

Jeżeli tutorial nie działa — najpierw sprawdź tę tabelę, potem oficjalną
dokumentację dla 3.x.

Ostrzeżenie `PerformanceWarning: draw_text is an extremely slow function`
pojawia się normalnie i **nie jest błędem** — arcade sugeruje, żeby przy wielu
napisach tworzyć obiekty `arcade.Text` raz w `__init__` i tylko je rysować.
Przy kilku napisach na ekranie można je zignorować.