/* Kompletně smazán původní a zastaralý obsah, lze ho případně dohledat na stránkách z předchozích let nebo v historii editů. */

====== Semestrální práce ======

Cílem semestrální práce je ověřit znalosti nabyté v rámci přednášek a cvičení, a umožnit studentům vyzkoušet si práci na větším projektu v Javě. Semestrální práci je možno vykonávat samostatně či ve dvojicích, větší skupiny nejsou dovoleny. Při práci ve dvojici se předpokládá, že rozsah celé práce bude větší než při samostatné práci. Studenti v týmu mohou být z různých paralelek - v tom případě se ale domluví s oběma cvičícími, u kterého z nich budou práci odevzdávat.


===== Zadání =====

Téma semestrální práce si můžete určit sami, a pro formalizaci zadání je určen první checkpoint (viz níže); případně si můžete vybrat jedno z předpřipravených témat níže. V tom případě se však očekává, že dané zadání "obohatíte" o vlastní netriviální funkcionalitu. Předpřipravená zadání vám také mohou sloužit jako vodítko pro vlastní téma, abyste stanovili dostatečný rozsah práce. Rozsah bude případně korigován vašim cvičícím v jednotlivých checkpointech.

  * [[courses:b0b36pjv:semestral:herni_engine|Herní engine]]
  * [[courses:b0b36pjv:semestral:simulace|Simulace]]
  * [[courses:b0b36pjv:semestral:arima|Arimaa]]

===== Nutné požadavky =====

Nehledě na vybrané téma **musí** každá odevzdaná práce splňovat následující požadavky:

  - Semestrální práce bude psána v Javě >=21 (či po domluvě se cvičícím v Kotlinu), a spravována pomocí Mavenu.
  - Práce bude mít doložitelný progress na GitLab. **Průběžně** (každou hotovou funkcionalitu s popisem) commitují **všichni** členové týmu. Pozor: neadekvátně málo commitů (velmi orientačně: méně než 10) obvykle vzbudí u cvičících (oprávněné) podezření na plagiát!
  - Oba účastníci projektu se musí podílet na tvorbě **GUI** pomocí platformy [[https://openjfx.io/|JavaFX]] (jiný framework pouze po dohodě). Alespoň jedna netriviální komponenta bude vytvořena bez použití [[https://gluonhq.com/products/scene-builder/|Scene Builderu]] či jiného "klikacího nástroje".
  - V projektu student předvede schopnost správně použít **vlákna** (za to se nepovažuje použití např. třídy ''Timer''). Například vytvořením hodin reálného času, které interagují s průběhem hry. Jelikož se jedná o aplikaci JavaFX, doporučuji používat třídy ''Task'' nebo ''Service'' namísto ''Thread''.
  - Několik netriviálních tříd bude pokryto **unittesty** nebo komplexnějším funkčním testem, za použití libovolného testovacího frameworku.
  - Budou použity **loggery**. Logovací zprávy bude možno zapnout nebo vypnout parametrem při spuštění, či jinou uživatelskou interakcí (**nikoliv** editací zdrojového kódu).
  - Stav aplikace (průběh hry, nastavení apod.) bude možné uložit. Preferovaný je zápis do souboru, je ale možné využít i jiné datové zdroje (např. databáze).
  - Veškeré netriviální ''public'' prvky v programu musí mít smysluplný **Javadoc** (v kódu, není třeba generovat dokument). Za triviální se považují například jednoduché gettery a settery bez vedlejších efektů.
  - Všechny netriviální části kódu budou vhodně **okomentovány**.
  - Ve Wiki projektu musí být aktuální a použitelný **uživatelský manuál** (viz příklad v CP3) a **technická dokumentace** programu - jeho vlastností, struktura projektu, použité technologie podle výše popsaných podmínek. Pozor, nejedná se o Javadoc!
  - Kód i komentáře v něm jsou psány **v angličtině**. Uživatelská a technická dokumentace může být psána i česky/slovensky.

V případě nesplnění některého z požadavků bude práce výrazně penalizována či vrácena studentovi k dopracování.
===== Odevzdání =====

Průběžná práce a samotné odevzdání semestrálních prací probíhá ve třech "Checkpointech", a to vždy v GitLab projektu, který vám byl automaticky založen na začátku semestru, a který naleznete na adrese ''%%https://gitlab.fel.cvut.cz/B252_B0B36PJV/username%%'' - tedy např. ''%%https://gitlab.fel.cvut.cz/B252_B0B36PJV/novakjan%%''. Jednotlivé checkpointy zároveň vždy nahrajte i pod patřičný upload do [[https://cw.felk.cvut.cz/brute|BRUTE]].

==== CP1 - Vize projektu ====

<note important>Termín odevzdání („deadline“): **8.3.2026**</note>

Cílem tohoto odevzdání je formalizovat zadání, na kterém budete dále pracovat. Zadání bude odevzdáno ve formě **PDF dokumentu** (případně wiki stránce ve vašem GitLab projektu) o rozsahu ~2x A4, ve kterém je popsáno kompletní fungování aplikace z pohledu uživatele, a který by měl obsahovat:
  * zvolené téma práce
  * manažerské shrnutí - 1 - 2 odstavce, představující vizi projektu
  * podrobný popis funkcionalit, které bude/nebude práce umět, jako:
    * průběh a cíl hry
    * vlastnosti postavy
    * popis předmětů ve hře, jejich vlastnosti (a případná interakce s nimi)
    * ovládání, způsob načítání a ukládání
    * a další...
  * pro lepší pochopení lze přidat obrázky jako wireframes obrazovek, náčrty herního pole nebo herních map, vizuální návrhy prvků aplikace, apod.

V této fázi byste tedy měli mít podrobně vymyšlený celý projekt, a mělo by stačit se pustit do programování. Pro inspiraci si můžete prohlédnout, jak by měla vypadat {{ :courses:b0b36pjv:semestral:cp1_correct.pdf |správně}} odevzdaná vize projektu, a jak naopak {{ :courses:b0b36pjv:semestral:cp1_wrong.pdf |špatná}} (vč. komentářů, co je na dokumentu špatně).

Cvičící bude hodnotit podrobnost dokumentu, jeho formu i rozsah celé práce.

==== CP2 - Objektový návrh ====

<note important>Termín odevzdání („deadline“): **12.4.2026**</note>

V rámci druhého checkpointu připravíte ve svém repozitáři (a odevzdáte pod patřičný upload do BRUTE):
  * kostru kódu
    * deklarace tříd, jejich vlastností a metod
    * dědičnost a další vazby mezi třídami
  * základní technickou dokumentaci
    * zjednodušený diagram tříd a vztahů mezi nimi
    * popis stavů hry/aplikace
    * použité technologie, knihovny, apod.
  * rozdělení práce mezi členy týmu (pokud pracujete ve dvojici)

Po tomto odevzdání by se základní struktura kódu neměla výrazně lišit, a mělo by stačit pouze doimplementovat předpřipravené třídy.

==== CP3 - Finální prezentace ====

<note important>Termín odevzdání („deadline“): **22.5.2026**</note>

Poslední checkpoint je zaměřen nejen na dokončení celého projektu dle zadání z CP1, ale i finální prezentaci, jejíž formu vám sdělí cvičící na hodině.

Součástí odevzdání je i uživatelská dokumentace, která může být formou uživatelského manuálu, a která zahrnuje všechny podstatné aspekty aplikace (včetně jejího spuštění!). Inspirací vám může být například [[https://shared.fastly.steamstatic.com/store_item_assets/steam/apps/12360/manuals/Manual-Global.pdf|tato příručka pro hru FlatOut UC]].

Dokončena by měla být i technická dokumentace, obohacena o dokumentaci ve formátu JavaDoc (není třeba generovat HTML formu!). Pokud bude použita komunikace po síti, doporučuje se specifikovat komunikační protokol - tedy jaká data a v jakém formátu se budou mezi serverem a klientem posílat.

<note important>
Kompletní práce se odevzdává během dvou posledních týdnů semestru. V případě dvojic se **oba** členové týmu **musí** zúčastnit odevzdání společně, a **oba musí** rozumět a být schopni odpovědět na otázky ohledně všech částí kódu (tedy nejen svých).


Jiný termín odevzdání je možný **pouze** ve výjimečných případech (nemoc, apod.) a po předchozí domluvě s cvičícím minimálně týden před oficiálním deadlinem!
</note>

===== Hodnocení =====

Za semestrální práci vám může být uděleno **maximálně 45 bodů**; **minimálně** však musíte získat:
  * **20 bodů** z celé práce;
  * **15 bodů** z finálního hodnocení (CP3);
  * **alespoň jeden bod** z **každé** položky níže.

Práce jsou hodnoceny dle následující tabulky:

^ ^Položka^Max bodů^Poznámka^
|**CP1**|Vize projektu          |5     |5b = jasně a podrobně popsaná vize projektu\\ 4–3b = mírné nejasnosti v částech popisu\\ 2–1b = výrazné nejasnosti v částech popisu či chybějící popis mechanik\\ 0b = příliš obecný popis, chybějící odevzdání |
|**CP2**|Objektový návrh        |7     |7b = jasný a podrobný objektový návrh\\ 6–4b = mírné nejasnosti/chyby v částech návrhu\\ 3–1b = výrazné nejasnosti/chyby v částech návrhu či chybějící vlastnosti/vazby\\ 0b = návrh bez vlastností/vazeb, chybějící odevzdání |
|**CP3**|Rozsah implementace    |10    |Plný počet za implementaci všech funkcí uvedených v zadání\\ až -2b za každou chybějící či nefunkční funkcionalitu                                             |
|:::|Kvalita kódu|10    |Plný počet za vhodně navržený datový model, minimum duplicitního kódu a snadnou rozšířitelnost\\ až -4b za nevhodnou strukturu tříd a metod\\ až -3b za neduhy v datovém modelu\\ až -3b za nečitelnost kódu (příliš dlouhé metody, jména proměnných apod.) |
|:::|Funkčnost                  |5     |Plný počet za korektní chování programu v běžných i hraničních případech\\ -2b za každý neošetřený "edge-case", spadnutí programu apod.         |
|:::|Dokumentace                |5     |až 2.5b za uživatelskou dokumentaci (instalace, návod k použití apod.)\\ až 2.5b za technickou dokumentaci (diagramy, popis architektury, JavaDoc v kódu)|
|:::|Správné použití GITu       |3     |3–2b = vhodné používání větví, merge requestů, issues apod.\\ 1b = základní práce s GITem (řádná velikost/pravidelnost commitů)\\ 0b = neprokazatelná historie (moc málo/moc velké commity)                          |
|               **Celkem bodů**||**45**|

Pozdní odevzdání **každého** z "checkpointů" je penalizováno 1b za každých započatých 72h.