TerraBot - let's explore and save the planet !

• Responsabili: Alina Tudorache, Dragos Dragan, Andrei Marcu, Francesco Martinut, Alexia Oprisan
• Colaboratori: Sorina-Anamaria Buf, Ștefan Cocioran, Florian-Luis Micu
• Data publicarii: TODO
• Deadline HARD: TODO
• Ultima modificare a cerinței: TODO
• Ultima modificare a scheletului: TODO
• Ultima modificare a testelor: TODO
• Schelet: https://github.com/oop-pub/

TerraBot, robotul nostru explorator de la NASA, are misiunea de a descoperi o nouă planetă și de a o pregăti pentru colonizare. El trebuie să parcurgă cât mai mult din suprafața planetei, să colecteze informații utile despre mediu și să contribuie la îmbunătățirea condițiilor de viață. Atenție însă: energia lui TerraBot este limitată, așa că fiecare acțiune trebuie aleasă cu grijă pentru a asigura succesul misiunii!

Scopul acestei teme este aplicarea cunoștințelor dobândite până acum, prin utilizarea conceptelor de programare orientată pe obiecte (OOP) în Java. Veți învăța să structurați un proiect într-un mod clar și organizat, să scrieți cod curat, modular și ușor de extins, care să permită adăugarea rapidă de noi funcționalități.

Proiectul propus va simula explorarea unei planete străine și va urmări evoluția mediului acesteia în funcție de anumiți parametri, simulare care se va dezvolta treptat pe măsură ce avansați.

Odată lansat în misiune, TerraBot intră într-un mediu complet necunoscut, unde fiecare colț de planetă ascunde provocări diferite. Robotul nostru este programat să efectueze simulări, fiecare având scopul de a observa cum evoluează ecosistemul, de a colecta date despre plante, animale, apă și sol, și de a aplica diferite metode pentru a menține mediul sănătos și sustenabil.

În cadrul acestor simulări, TerraBot experimentează, învață și ia decizii bazate pe informațiile colectate. Fiecare simulare reprezintă o rundă completă de explorare: mediul se modifică, resursele sunt limitate, iar robotul trebuie să acționeze eficient pentru a-și atinge obiectivele. Astfel, testele voastre pot conține una sau mai multe simulări, oferindu-vă posibilitatea de a evalua performanța TerraBot în scenarii diferite.

Pașii pentru desfășurarea unui test sunt următorii:

1. Se generează preambulul – harta cu toate entitățile plasate pe celule (vezi secțiunea Desfășurarea simulării).
2. Se dau comenzile pentru simulare:
   1. startSimulation → marchează începutul simulării
   2. se rulează pașii propriu-ziși ai simulării (TerraBot primește comenzi, mediul se actualizează)
   3. endSimulation → marchează finalul simulării.
   4. dacă există alte simulări în cadrul aceluiași test, pașii de mai sus se repetă.

Fiecare simulare trebuie să înceapă cu comanda `startSimulation` și să se încheie cu `endSimulation`. Doar comenzile aflate între aceste două marcaje sunt valide și vor fi executate. Astfel, o simulare este considerată validă numai dacă are atât început, cât și sfârșit.

În timpul explorării, două lucruri se întâmplă în paralel:

1. Mediul evoluează automat – fenomene naturale care se petrec fără intervenția robotului
   • calitatea aerului, a solului și a apei se modifică în timp (în aceasta ordine)
   • plantele își schimbă starea (pot crește și se pot ofili)
   • animalele se deplasează și își schimbă starea (consumă plante sau apă ca să nu fie flămânde)
2. TerraBot ia decizii și acționează – sub controlul comenzilor primite:
   • se deplasează pe hartă
   • scanează și analizează elementele întâlnite, învățând „facts” pe care le stochează
   • aplică metode de îmbunătățire a mediului (trebuie mai întâi să învețe cum să facă asta pe baza unor „facts” descoperite anterior)
   • colectează plante și le adaugă în inventar
   • explorează noi zone, alegând cel mai bun drum în funcție de calitatea mediului.

Fiecare pas al simulării presupune atât actualizarea automată a mediului, cât și procesarea comenzilor robotului, deci trebuiesc validate toate aceste evenimente!

În harta din imagine puteți vedea un exemplu orientativ cu poziționarea robotului și mișcările pe care poate să le efectueze pe hartă. Aceasta are o dimensiune de NxN dată la input, cât și condițiile de mediu și animalele/plantele pentru fiecare căsuță.

Detaliile privind mișcările și acțiunile robotului, precum și schimbările automate ale mediului, sunt descrise în secțiunea Comenzi

• marcheaza inceperea unei simulari
• robotul porneste mereu de pe pozitia [0, 0] a hartii

Mesaje posibile pentru aceasta comanda:

• "Simulation has started."
• "ERROR: Simulation already started. Cannot perform action"

• marcheaza sfarsitul unei simulari

Mesaje posibile pentru aceasta comanda:

• "Simulation has ended."
• "ERROR: Simulation already started. Cannot perform action"

• marcheaza un fenomen meteo care produce schimbari pentru aer
• Valorile posibile pentru tipul de schimbare meteo:
  • desertStorm → desert air
  • peopleHiking → mountain air
  • newSeason → temp air
  • polarStorm → polar air
  • rainfall → tropical air

Mesaje posibile pentru aceasta comanda:

• "The weather has changed."
• "ERROR: The weather change does not affect the environment. Cannot perform action"
• "ERROR: Simulation already started. Cannot perform action"

• returnează energia curenta a TerraBot-ului

• se printeaza pentru patratica curenta urmatoarele:
  • tipul de planta, daca exista
  • tipul de animal, daca exista
  • tipul de sursa de apa, daca exista
  • componenta solului
  • componenta aerului

• se printeaza pentru fiecare patratica de pe harta urmatoarele:
  • nr total enitati de pe patratica (sum(plant, animal, water_source))
  • calitate aerului
  • calitatea solului

• afiseaza pentru fiecare tip de obiect fact-urile invata
  • exemplu: s-a scanat si invatat despre red algae, se printeaza toate facts despre red algae

În rezolvarea temei va fi nevoie de folosirea unor obiecte pentru stocarea și maparea datelor primite în format JSON. Scheletul temei vă oferă mai multe clase utile pentru citirea și rularea temei. Acestea se regăsesc în cadrul scheletului astfel:

• Clasele de input din cadrul pachetului fileio : Acestea se vor folosi pentru parsarea datelor de input. Astfel preluați toate informațiile necesare pentru a crea propriile clase pentru rezolvarea temei.
• Clasa Main care este punctul de intrare pentru logica de rezolvare a temei.

Pentru a întelege mai bine cum funcționează citirea/scrie în fișierele JSON vă recomandăm să citiți Json & Jackson.

1. Se încarcă datele citite din fișierul de test, în format JSON, în obiecte.
2. Se primesc secvențial acțiuni și se execută pe măsură ce sunt primite, rezultatul lor având efect asupra Repository-ului.
3. După executarea unei acțiuni, se afișează rezultatul ei în fișierul JSON de ieșire.
4. La terminarea tuturor acțiunilor se termină și execuția programului.

• Tema a fost concepută pentru a vă testa cunoștințele dobândite în urma parcurgerii laboratoarelor 1-3, aceasta putând fi rezolvată doar cu noțiunile invățate din acele laboratoare.
• Tema fiind o specificație destul de stufoasă recomandăm citirea de cel putin două ori a enunțului inainte de inceperea implementării.
• Pentru depanarea diferențelor dintre output-ul vostru si fișierele ref, vă recomandăm acest site.

Punctajul constă din:

• 80p implementare - trecerea testelor
• 10p coding style (vezi checkstyle)
• 5p README clar, concis, explicații axate pe design (flow, interacțiuni)
• 5p folosire git pentru versionarea temei

Depunctările pentru designul și organizarea codului se vor scădea din punctajul testelor. Dacă vor apărea depunctări specifice temei în momentul evaluării, nemenționate pe pagina cu depunctări generale, ele se vor încadra în limitele de maxim 10p pentru design, 5p pentru readme. Dacă tema nu respecta cerințele, sau are zero design OOP atunci se pot face depunctari suplimentare.

Folosirea git pentru versionare va fi verificata din folderul .git pe care trebuie să îl includeți în arhiva temei. Punctajul se va acorda dacă ați făcut minim 3 commit-uri relevante și cu mesaj sugestiv. NU este permis să aveți repository-urile de git publice până la deadline-ul hard.

Bonusuri: La evaluare, putem oferi bonusuri pentru design foarte bun, cod bine documentat dar și pentru diverse elemente suplimentare alese de voi.

Unul din obiectivele temei este învățarea respectării code-style-ului limbajului pe care îl folosiți. Aceste convenții (de exemplu cum numiți fișierele, clasele, variabilele, cum indentați) sunt verificate pentru temă de către tool-ul checkstyle.

Pe pagina de Recomandări cod găsiți câteva exemple de coding style.

Dacă numărul de erori depistate de checkstyle depășește 30, atunci punctele pentru coding-style nu vor fi acordate. Dacă punctajul este negativ, acesta se trunchiază la 0.

Exemple:

• punctaj_total = 100 și nr_erori = 200 ⇒ nota_finala = 90
• punctaj_total = 100 și nr_erori = 29 ⇒ nota_finala = 100
• punctaj_total = 80 și nr_erori = 30 ⇒ nota_finala = 80
• punctaj_total = 80 și nr_erori = 31 ⇒ nota_finala = 70

Arhiva o veţi urca pe VMChecker, unde sunt si informații despre structura ei.

Q: Pot folosi biblioteca “X”?
A: Dacă doriți să folosiți o anumită bibliotecă vă recomandăm să întrebați pe forum, ca apoi să o validăm și să o includem și pe Vmchecker.

Q: Am descoperit edge case-ul “Y”, trebuie să îl tratez?
A: Nu. Toate datele necesare pentru soluționarea temei vă sunt date in cerință. Dacă totuși am omis ceva ne puteți contacta pe forum.

Q: Pot folosi clase de tip “Enum” pentru constante?
A: Da.

Q: Ce JDK recomandați?
A: 25

Q: Pot să fac în orice ordine testele?
A: Da! Testele au fost concepute sa fie cât mai decuplate și să testeze câte o funcționalitate în întregime. Cu toate astea, vă recomandăm să implementați mai întâi testele 01, 02, 03 deoarece reprezintă funcționalitățile de bază pentru rezolvarea următoarelor teste mai complexe.

• Schelet de cod
• Forum
• Indicații pentru teme
• Recomandări coding style & javadoc