Zadanie 1 - Gaming Stats Calculator

PEVŠ ZAPR 2025 - Semestrálny projekt 1

Prihlásenie na zadanie

Important

Pre prihlásenie sa na zadanie 1 je potrebné mať aktívny GitHub účet. Účet je bezplatný. Pre vypracovanie môžte použiť existujúci GitHub účet alebo si účet môžte vytvoriť na stránke GitHub.

Zadanie je distribuované aj odovzdané pomocou platformy GitHub, modulu Classroom. Pre prihlásenie sa na vypracovanie zadania sa prihláste svojim účtom na platformu GitHub a následne kliknite na tento odkaz:

https://classroom.github.com/a/e4HA9Gd3

Po potvrdení sa vám vytvorí súkromný repozitár s nastaveným projektom a so znením zadania v súbore README.md (znenie zadanie sa nachádza aj nižšie ⬇). Pozorne si zadanie prečítajte pre začatím vypracovania.

Vypracujte zadanie samostatne a podľa svojich najlepších schopností a vedomostí. Implementáciu môžte priebežne pushovať do repozitára až do uplynutia termínu, ktorý je uvedený v zadaní a bude oznámený aj v MS Teams.

Pri každej aktualizácii kódu GitHub repozitáry je spustená GitHub automatizácia, ktorá overí, či váš kód je skompilovateľný a spustiteľný a testovateľný podľa krítérií zadania.

V prípade otázok, problémov alebo akejkoľvek potreby konzultácií môžte kontaktovať cvičiaceho na MS Teams alebo emailom.

🎮 Gaming Stats Calculator - Kalkulátor herných štatistík

Cieľom zadania je implementovať jednoduchú konzolovú aplikáciu (tzv. CLI - command line interface), ktorá vypočíta herné štatistiky hráča na základe vstupných parametrov.

Program poskytne používateľovi možnosti zadania rôznych konfigurácii vstupov pre výpočet hráčskej štatistiky. Celý výpočet prebehne v jednom spustení programu. Program nepracuje so súbormi ani nepracuje so žiadnym externým zdrojom. Program po vypočítaní a vypísaní hráčskej štatistiky, podľa zadaných parametrov, skončí.

Program po skompilovaní je spustení z konzoly/terminálu s tzv. pomenovaným argumentami (options)

./gamestats --help

Hra - vstupy

Vstupmi programu je vyjadrená jedna hra. Hra pozostáva u nasledovných metrík:

  • Počet zabití (kills)
  • Počet úmrtí (deaths)
  • Počet asistencií (assists)
  • Trvanie hry (duration)

Funkcionalita

Vstupy a argumenty

Program príjma povinné argumenty, t.j. musia byť všetky povinné argumenty uvedené pri spustení programu, inak program vypíše chybu, ktorý povinný argument pri volaní chýbal. A nepovinné argumenty, ktoré dopĺňajú funkcionalitu programu pre ďalšie štatistiky.

Povinné argumenty:

  • --kills POCET - počet zabití, celé číslo (int)
  • --deaths POCET - počet úmrtí, celé číslo (int)
  • --assists POCET - počet asistencií, celé číslo (int)
  • --duration MINUTY - trvanie hry v minútach, celé číslo (int)

Voliteľné argumenty:

  • --headshots POCET - počet headshotov z uvedeného počtu zabití, celé číslo (int)
  • --teamkills POCET - počet teamkills na vlastný tým, celé číslo (int)
  • --mvp - získal MVP (Most Valuable Player) príznak. Argument nemá ďalšiu hodnotu, ak je prítomný pri spustení programu, tak program použije tento príznak pri výpise a výpočet celkového skóre.

Pomocné príkazy:

  • --help - zobrazí nápovedu/pomocný text
  • --ranks - zobrazí rebríček rankov/stupňov

Príklady volania programu:

  • ./gamestats --help
  • ./gamestats --ranks
  • ./gamestats --kills 25 --deaths 10 --assists 15 --duration 35
  • ./gamestats --kills 25 --deaths 10 --assists 15 --duration 35 --headshots 5 --mvp

Výpočet štatistík

Program po spustení a prečítaní argumentov vypočíta štatistiku hry hráča. Program vypočíta nasledovné metriky hry:

  • Kills/Deaths ratio (K/D) - Pomer Kills/Deaths (Zabití/Úmrtí)
  • Kill,Assists/Deaths ratio (KDA) - Pomer K/D aj s asistenciami podľa vzorca: (Kills + Assists) / Deaths
  • Kills per minute (KPM) - Počet zabití za minútu hry, podľa vzorca: Kills / Duration
  • Action per minute (APM) - Počet akcií za minútu hry, podľa vzorca: (Kills + Assists) / Duration
  • Performance score - Celkové skóre podľa načítaných bodov podľa vstupov. Ku vypočítanému skóre hra podľa definovanej tabuľky (viď Rank System) priradí rank/stupeň schopností hráča.

Výpočet celkového skóre:

Celkové skóre sa vypočíta podľa nasledujúceho vzorca:

Performance Score = (KDA × 10) + (KPM × 30) + Headshots × 2 + MVP bonus: +20 - Team Kills × 50

Na základe celkového skóre je priradení hráčovi rank/stupeň podľa nasledovnej stupnice:

Rank System:

  • < 0: Noob
  • 0-20: Iron
  • 21-40: Bronze
  • 41-60: Silver
  • 61-75: Gold
  • 76-85: Platinum
  • 86-92: Diamond
  • 93-97: Master
  • 98-100: Grandmaster
  • > 100: Godlike

Výstup

Program po výpočte štatistík vypíše tieto metriky na obrazovku (konzolu/terminál) pre používateľa v nasledujúcom formáte:

====== GAMING STATS ======
Kills:           <číslo na vstupe>
Deaths:          <číslo na vstupe>
Assists:         <číslo na vstupe>
Duration:        <číslo na vstupe> min
Headshots:       <číslo na vstupe>
Team Kills:      <číslo na vstupe>
MVP:             <TRUE ak je argument --mvp prítomný>
--------------------------
K/D:             <vypočítaná K/D hodnota>
KDA:             <vypočítaná KDA hodnota>
KPM:             <vypočítaná KPM hodnota>
APM:             <vypočítaná APM hodnota>
Performance:     <počet celkového skóre>/100
Rank:            <rank získaný na základe celkového skóre>
==========================

Vo formáte znázorňuje text medzi znakmi < a > inštrukciu aká hodnota sa tam má zobraziť. Riadky zobrazujúce hodnotu nepovinných argumentov sa nemajú zobraziť ak ich hodnota nie je zadaná.

Príklad výstupu: 

====== GAMING STATS ======
Kills:           7
Deaths:          4
Assists:         10
Duration:        35 min
Headshots:       2
--------------------------
K/D:             1.75
KDA:             4.25
KPM:             0.20
APM:             0.49
Performance:     52.50/100
Rank:            Silver
==========================

Implementácia

V rámci implementácie môžte použiť všetky štandardné funkcie knižnice jazyka C, v štandarde C17. Kód musí byť skompilovateľný základnou inštaláciou programu GCC, takže pozor na Windows/Mac špecifické kompilátory.

Funkcionalitu programu rozdelte do niekoľkých funkcií, ktoré následne použijete v programe. V zdrojovom kóde programu by teda mali byť definované minimálne 4 funkcie (ideálne viac):

  • main funkcia programu
  • vypísanie pomocného text
  • výpočet metrík štatistiky
  • výpočet celkového skóre a rankingu

Program implementujte v jednom súbore main.c, ktorý musí byť umiestnený v priečinku src v tomto repozitáry. Ak je zdrojový súbor umiestnený na inom mieste, alebo bude nazvaný iným menom, nebude braný pri kompilácii do úvahy, a teda ani pri hodnotení.

Pri spracovaní vstupov sa môžte inšpirovať článkom Práca s argumentami programu v jazyku C na stránke predmetu, alebo inými technikami uvedených na internete. Pre pokročilejších, pre spracovanie argumentov môžte použiť aj funkciu getopt_long z knižnice getopt.h. Dokumentáciu nájdete napríklad tu alebo tu.

Pri implementácii si môžte vypomáhať s AI nástrojmi, pre inšpiráciu, riešenie problémov, či testovanie avšak je prísne zakázané priame generovanie kódu vypracovania zadania, či kopírovanie väčších častí kódu z AI či internetu. Táto práca je ukážkov vašich schopností a vedomostí programovania nie definovania promptu do AI.

Kompilácia

Pre testovanie je možné kód skompilovať príkazom:

gcc -std=c17 -o bin/gamestats -Wall -Wextra src/main.c

Kompilátor vytvorí spustený program v priečinku bin v repozitáry.

Git

Zdrojový kód tohto projektu je manažovaný verziovacím systémom Git. Pomocou Gitu je toto vypracovanie zadania aj odovzdané. Pre oboznámenie práce s Gitom si prečítajte tento článok Git pre začiatočníkov alebo akýkoľvek iný tutoriál na internete.

Pre kontrolu kompilácie je v repozitáry nastavená automatizácia cez GitHub Actions pipeline. Pipeline sa spustí automaticky pri aktualizácii kódu vo vetve main (napr. git push). GitHub zdrojový súbor src/main.c skompiluje pomocou poslednej verzie kompilátora GCC pre štandard jazyka C17. Pipeline následne pokračuje jednoduchým testom spustenia programu. Spustenie je testované a zaznamenané pomocou programu tui-test a na konci pipeline je vypísaný výsledok takého testu. Pipeline vždy testuje posledný commit vo vetve main a testuje program s argumentom --help. Pre správnu kontrolu programu musí nápoveda/pomocný text programu obsah slovo “Help”. Pipeline je možné spustiť ľubovoľný počet krát. Spustenie pipeline je možné vidieť v záložke Actions vo vašom repozitáry zadania.

Hodnotenie

Zadanie je ohodnotené 20 bodmi. Odovzdaný program musí byť skompilovateľný kompilátorom GCC a spustiteľný, inak je hodnotený 0 bodmi. Pri hodnotení vypracovania zadania sa kontroluje originalita odovzdaného vypracovania medzi všetkými študentmi a zároveň aj voči AI nástrojom (kód vygenerovaný pomocou ChatGPT, Gemini a Claude Sonnet). Vypracovanie so zhodou vyššou ako 80% sú hodnotené 0 bodmi. Hodnotený je iba kód ku poslednému commitu vo vetve main, ktorý bol urobený do termínu odovzdania.

Vypracovanie bude podrobené automatizovaným testom, ktoré budú prevolávať program s definovanými argumentami a kontrolovať obsah výstupu programu. Je teda veľmi dôležité dodržať špecifikáciu argumentov, ako aj formát výstupu programu pre používateľa. Výsledky automatizovaných testov budú zverejnené do tohto repozitára do vetvy feedback. V prípade chyby v testoch, budú testy spustené znovu a nový výsledkom zverejnený. Po uplynutí termínu odovzdania zadania budú definície testov zverejnené a ak v nim nájdete chybu prosím nahláste ju sem ako nové GitHub issue.

Vypracovanie bude hodnotené aj ručne. Pri hodnotení vypracovania sa bude prihliadať na:

  • práca s premennými
  • definovanie control flow programu
  • definovanie vlastných funkcií a ich použitie
  • spracovanie argumentov
    • Kontrola záporných hodnôt
    • Kontrola delenia nulou (0 deaths → K/D = kills)
    • Kontrola neplatných hodnôt argumentov (napr. znak namiesto čísla)
  • komunikácia chybového stavu programu používateľovi
  • štrukturovanie kódu
  • dodržanie špecifikácie zadania

Odovzdanie

Po prihlásení sa na zadanie 1 cez GitHub Classroom vám je automaticky vytvorená kópia repozitára, ktorý bude nastavený ako privátny pre vás na vypracovanie (t.j. máte povolený commit a push do repozitára). Skontrolujte si, či sa váš repozitár nachádza pod skupinou Interes-Group, inak vyučujúci nemajú prístup ku vášmu repozitáru a zadanie sa nepovažuje za odovzdané. Ak sa vám repozitár nevytvorí ihneď kontaktuje vyučujúceho na MS Teams alebo na univerzitnom emaily. Je prísne zakázané dávať prístup k vášmu repozitára inému študentovi, alebo osobe, ktorá nie je vyučujúci. V repozitáry by sa mali vytvoriť dve vetvy main a feedback a vytvorí sa tzv. pull request z vetvy main do vetvy feedback. Váš kód pushujte (t.j. git push) do vetvy main. Hodnotenie vypracovania, ako aj komentár ku kódu, uvidíte v danom pull requeste. Ak sa vám vetva feedback alebo pull request nevytvorí ihneď kontaktuje vyučujúceho na MS Teams alebo na univerzitnom emaily.

V repozitáry upravujte iba súbory pod priečinkom src. Ostatné súbory je zakázané upravovať, predovšetkým súbory pre kompiláciu, súbory obsahujúce GitHub pipeline (.github) a súbory obsahujúce automatizované testy (priečinok test). Pri zmene týchto súborov môže byť vypracovanie ohodnotené 0 bodmi.

Vypracovanie zadania priebežne commitujte (git commit)/pushujte (git push) do repozitára vytvoreného GitHubom pre toto zadanie. Váš kód commitujte/pushujte do vetvy main. Hodnotený bude posledný commit/push do termínu odovzdania vypracovania. Vypracovanie je nutné odovzdať/commitnúť/pushnúť do repozitára do 16.11.2025 23:59. Neodovzdanie je hodnotené 0 bodmi.

V prípade otázok, alebo technických problémov môžete kontaktovať vyučujúcich na MS Teams alebo na univerzitnom emaily.

✨ Bonus - Porovnanie hier (+3 body)

Ako bonus môžte implementovať porovnanie štatistík viacerých hier naraz. Vstupy pre jednu hru sú zachované, avšak je potrebné implementovať nové argumenty --compare a --game ktoré pracujú so vstupmi pre viacero hier.

Argument --compare spustí program v porovnávacom móde a ďalšie argumenty, ktoré bude spracovávať len argumenty s meno --game. Argumentov s prepínačom --game musia byť minimálne 2 (aby bolo čo porovnávať). Hodnota argumentu --game je string, ktorý obsahuje vstupy pre jednu hru, ako podľa pôvodnej definície programu. Vstupy ako aj štatistiky pre jednu hru sú spracované rovnako ako v pôvodnej verzii programu.

Režim porovnania viacerých hier:

./gamestats --compare \
  --game "--kills 25 --deaths 10 --assists 15 --duration 35" \
  --game "--kills 30 --deaths 5 --assists 20 --duration 40" \
  --game "--kills 15 --deaths 15 --assists 10 --duration 30"

Ako výstup programu v porovnávacom móde vypíšte tabuľku jednotlivých vypočítaných štatistík hier pod seba pre prehľadné porovnanie. Pod tabuľkou vypíše, ktorá hra získala na najvyššie skóre a teda bola najúspešnejšia a priemerné skóre za všetky hry.

Ukážka výpisu programu pre tri hry:

GAME | K/D   | KDA   | KPM  | APM  | SCORE  | RANK
  1  | 2.50  | 4.00  | 0.71 | 1.14 | 61.30  | Gold
  2  | 6.00  | 10.00 | 0.75 | 1.25 | 122.50 | Godlike
  3  | 1.00  | 1.67  | 0.50 | 0.83 | 31.70  | Bronze
--------------------------------------------
BEST GAME: #2 (Godlike)
AVG SCORE: 71.83

Testovanie

Program odporúčam otestovať lokálne pomocou rôznej konfigurácie príkazov. Nižšie je uvedených niekoľko príkladov volania programu a aký výstup by mali dať.

Program odporúčam pravidelne kompilovať aby ste sa vyhli zbytočnému opravovaniu veľkých kusov kódu ak by sa vyskytla chyba.

Príklady volaní a očakávané výstupy:

  1. Iba povinné argumenty
./gamestats --kills 25 --deaths 10 --assists 15 --duration 35
====== GAMING STATS ======
Kills:           25
Deaths:          10
Assists:         15
Duration:        35 min
--------------------------
K/D:             2.50
KDA:             4.00
KPM:             0.71
APM:             1.14
Performance:     61.3/100
Rank:            Gold
==========================
  1. S MVP označením
./gamestats --kills 30 --deaths 5 --assists 20 --duration 40 --mvp
====== GAMING STATS ======
Kills:           30
Deaths:          05
Assists:         20
Duration:        40 min   
MVP:             TRUE
--------------------------
K/D:             6.00
KDA:             10.00
KPM:             0.75
APM:             1.25
Performance:     142.50/100
Rank:            Godlike
==========================
  1. S headshots argumentom
./gamestats --kills 25 --deaths 10 --assists 15 --duration 35 --headshots 18
====== GAMING STATS ======
Kills:           25
Deaths:          10
Assists:         15
Duration:        35 min
Headshots:       18         
--------------------------
K/D:             2.50
KDA:             4.00
KPM:             0.71
APM:             1.14
Performance:     97.30/100
Rank:            Grandmaster
==========================
  1. S teamkill penalizáciou
./gamestats --kills 20 --deaths 8 --assists 12 --duration 30 --teamkills 2
====== GAMING STATS ======
Kills:           20
Deaths:          08
Assists:         12
Duration:        30 min       
Team Kills:      02           
--------------------------
K/D:             2.50
KDA:             4.00
KPM:             0.67
APM:             1.07
Performance:     -39.90/100
Rank:            Noob
==========================
  1. S viacerými voliteľnými argumentmi
./gamestats --kills 20 --deaths 8 --assists 12 --duration 30 --headshots 15 --mvp
====== GAMING STATS ======
Kills:           20
Deaths:          08
Assists:         12
Duration:        30 min
Headshots:       15     
MVP:             TRUE
--------------------------
K/D:             2.50
KDA:             4.00
KPM:             0.67
APM:             1.07
Performance:     110.10/100
Rank:            Godlike
==========================

Automatizované testovanie

Tento repozitár obsahuje aj nastavenie pre automatizované testovanie pomocou nástroje tui-test. Tento program je založený na jazyku Typescript a je spúšťaný pomocou Node.js. Všetky testy a nastavenia sú uchované v priečinku test a prísne zakázané ich prípadnú zmenu pushnúť do repozitára na odovzdanie. Pre tých, ktorý ovládajú tento jazyk a sú schopný si rozšíriť test suite o vlastné testy pokojne môžu, len ich nikde nezdielajte a nepushujte do repozitára na GitHube na odovzdanie.

Návod pre nastavenie a spustenie testov

Prerekvizity:
  • Nainštalovaný Node.js (verzia 16.6.0 alebo vyššia)
  • Nainštalovaný npm (Node Package Manager)
  • Skompilovaný program gamestats v priečinku bin/
Postup:
  1. Skompilujte program (ak ste to ešte neurobili):
mkdir -p bin
gcc -std=c17 -o bin/gamestats -Wall -Wextra src/main.c
  1. Prejdite do priečinka test:
cd test
  1. Nainštalujte závislosti:
npm install
  1. Spustite testy:
npm test

Alternatívne spustenie:

Môžete použiť priamo nástroj tui-test:

cd test
npx @microsoft/tui-test
Čo testy kontrolujú:

Testy používajú nástroj tui-test od Microsoftu, ktorý:

  • Spúšťa váš program s rôznymi argumentami
  • Zachytáva výstup programu v termináli
  • Porovnáva výstup s očakávanými výsledkami (uložené v __snapshots__)
  • Overuje formát výstupu a správnosť výpočtov