Εργασία 1

• Ανακοινώθηκε: 8/4/2024
• Προθεσμία παράδοσης: 3/5/2024 23:59
• 16% του συνολικού βαθμού στο μάθημα
• Link εγγραφής: https://classroom.github.com/a/PAx-GOn_
• Demo: https://k08.chatzi.org/games/2024/solution/game.html

Σημαντικό: διαβάστε τις οδηγίες (κοινές για όλες τις εργασίες). Περιέχουν μεταξύ άλλων και πληροφορίες για τη χρήση του git, η οποία είναι ολόιδια με τα εργαστήρια.

Στην εργασία αυτή θα χρησιμοποιήσετε έτοιμη υλοποίηση για τους περισσότερους ΑΤΔ που είδαμε στο μάθημα, η οποία παρέχεται από τη βιβλιοθήκη k08.a στο git repository της εργασίας. Τον κώδικα τον κάνουμε compile όπως έχουμε δει στο μάθημα. Στα Windows χρειάζεστε επιπλέον το εργαλείο VcXsrv, δείτε τις οδηγίες για WSL.

Γενικά

Στην εργασία αυτή καλείστε να υλοποιήσετε ένα video game με γραφικό interface και interactive gameplay, παραλλαγή του κλασσικού Asteroids. Στο παιχνίδι αυτό ένα διαστημόπλοιο εξερευνεί το αχανές διάστημα, προσπαθώντας να αποφύγει αστεροειδείς που εμφανίζονται στο δρόμο του. Σκοπός του παιχνιδιού είναι το διαστημόπλοιο να ταξιδέψει όσο περισσότερο γίνεται, ελαχιστοποιώντας τον αριθμό των αστεροειδών που καταστρέφει (ή που συγκρούεται μαζί τους).

Για την υλοποίηση του γραφικού interface του παιχνιδιού θα χρησιμοποιήσετε τη βιβλιοθήκη raylib η οποία περιέχεται στο repository της εργασίας. Η βιβλιοθήκη υποστηρίζει όλα τα βασικά λειτουργικά συστήματα, αλλά και δίνει τη δυνατότητα να κάνουμε compile το παιχνίδι σε μορφή που μπορεί να ενσωματωθεί σε μια web σελίδα.

Είναι παράδειγμα υλοποίησης του παιχνιδιού υπάρχει εδώ.

Modules και information hiding. Η διαχείριση της κατάστασης του παιχνιδιού γίνεται από το module state.h, που θα βρείτε στο repository της εργασίας:

• include/state.h : το interface
• modules/state.c : η υλοποίηση που θα φτιάξετε

Σε ένα τέτοιο project οφείλουμε να διαχωρίσουμε τον κώδικα που διαχειρίζεται την κατάσταση του παιχνιδιού (module state.h), από τον κώδικα που διαχειρίζεται το interface (module interface.h, θα το φτιάξουμε αργότερα). Για το λόγο αυτό, κάθε module θα πρέπει να εμφανίζει στο χρήστη μόνο τις πληροφορίες που είναι απαραίτητες, και όχι πληροφορίες που αφορούν την εσωτερική λειτουργία του. Οι “δημόσιες” αυτές πληροφορίες βρίσκονται στο state.h, ενώ πληροφορίες που αφορούν την υλοποίηση βρίσκονται μέσα στο state.c.

Για τη διαχείριση δισδιάστατων γραφικών είναι επίσης χρήσιμο το module vec2.h το οποίο υλοποιεί απλές λειτουργίες σε δισδιάστατα διανύσματα.

Game example. Ένα πολύ απλό παράδειγμα παιχνιδιού υπάρχει στο directory programs/game_example στο repository της εργασίας. Συστήνεται ισχυρά να μελετήσετε τη δομή και τον κώδικα του παραδείγματος πριν ξεκινήσετε την εργασία.

Άσκηση 1 (15%)

Στο αρχείο modules/state.c είναι ήδη υλοποιημένη η συνάρτηση state_create η οποία δημιουργεί την αρχική κατάσταση state του παιχνιδιού. Η κατάσταση state περιλαμβάνει τις θέσεις όλων των αντικειμένων και άλλες πληροφορίες για το παιχνίδι.

Αρχικά μελετήστε τον κώδικα της state_create και κατανοήστε τους τύπους που χρησιμοποιούνται (State, Object, StateInfo) και τα περιεχόμενα της κατάστασης του παιχνιδιού.

Στη συνέχεια υλοποιήστε τις ακόλουθες συναρτήσεις του module state.h :

// Επιστρέφει τις βασικές πληροφορίες του παιχνιδιού στην κατάσταση state
StateInfo state_info(State state);

// Επιστρέφει μια λίστα με όλα τα αντικείμενα του παιχνιδιού στην κατάσταση state,
// των οποίων η θέση position βρίσκεται εντός του παραλληλογράμμου με πάνω αριστερή
// γωνία top_left και κάτω δεξιά bottom_right.
List state_objects(State state, Vector2 top_left, Vector2 bottom_right);

Τέλος, χρησιμοποιώντας τις συναρτήσεις αυτές, δημιουργήστε ένα unit test που να ελέγχει την ορθότητα της state_create. Στο αρχείο tests/state_test.c υπάρχει η βασική δομή του test, το οποίο πρέπει να επεκτείνετε (δε χρειάζεται πρόγραμμα που να παίρνει είσοδο από το χρήστη, μόνο το unit test). Το test δεν χρειάζεται να είναι εξαντλητικό, αλλά να ελέγχει τα βασικά χαρακτηριστικά της κατάστασης που δημιουργεί η state_create, πχ τον αριθμό, τις συντεταγμένες, κλπ, των αντικειμένων. Επίσης το test θα πρέπει να δοκιμάζει κλήσεις της state_objects για 2 διαφορετικές τιμές των top_left,bottom_right.

Άσκηση 2 (20%)

Συνεχίζοντας την υλοποίηση του παιχνιδιού, καλείστε να υλοποιήσετε μέρος της τελευταίας συνάρτησης του module stats.h:

// Ενημερώνει την κατάσταση state του παιχνιδιού μετά την πάροδο 1 frame.
// Το keys περιέχει τα πλήκτρα τα οποία ήταν πατημένα κατά το frame αυτό.
void state_update(State state, KeyState keys);

Η κατάσταση του παιχνιδιού ενημερώνεται ανάλογα με τα πλήκτρα που είναι πατημένα στο συγκεκριμένο frame (παράμετρος keys) με βάση τους ακόλουθους κανόνες:

• Κίνηση αντικειμένων: τόσο η θέση όσο και η ταχύτητα κάθε αντικειμένου είναι διανύσματα που περιέχονται στον τύπο Object. Εφόσον η ταχύτητα εκφράζεται σε pixels/frame, η θέση σε κάθε update ενημερώνεται απλά προσθέτωντας το διάνυσμα της ταχύτητας σε αυτό της προηγόυμενης θέσης.

• Περιστροφή διαστημοπλοίου: αν το αριστερό ή το δεξί πλήκτρο είναι πατημένο, τότε το διαστημόπλοιο περιστρέφεται κατά SPACESHIP_ROTATION αριστερά ή δεξιά αντίστοιχα.

• Επιτάχυνση διαστημοπλοίου: αν το πάνω βέλος είναι πατημένο, τότε η ταχύτητα του διαστημοπλοίου μεταβάλλεται, προσθέτωντας το διάνυσμα επιτάχυνσης σε αυτό της ταύτητας. Το διάνυσμα επιτάχυνσης προκύπτει πολλαπλασιάζοντας με SPACESHIP_ACCELERATION το διάνυσμα κατεύθυνσης του διαστημοπλοίου.

• Επιβράδυνση διαστημοπλοίου: αν το πάνω βέλος δεν είναι πατημένο, τότε η ταχύτητα του διαστημοπλοίου μειώνεται κατά SPACESHIP_SLOWDOWN, διατηρώντας την ίδια κατεύθυνση με πριν.

• Παύση και διακοπή:

  • Αν πατηθεί P το παιχνίδι μπαίνει σε pause και δεν ενημερώνεται πλέον.
  • Αν το παιχνίδι είναι σε pause και πατηθεί N τότε ενημερώνεται για μόνο 1 frame (χρήσιμο για debugging).

Είστε ελεύθεροι να προσαρμόσετε τους κανόνες αυτούς, σε λογικά πλαίσια, ανάλογα με το interface που θα υλοποιήσετε αργότερα.

Τέλος, επεκτείνετε το tests/test_state.c ώστε να ελέγχει τη λειτουργία της state_update. Δεν χρειάζεται στο test να ελέγξετε όλο το functionality της state_update, αρκεί μόνο ο έλεγχος ότι οι ιδιότητες του διαστημοπλοίου ενημερώνονται σωστά ανάλογα με τα πλήκτρα που είναι πατημένα. Δεν απαιτούνται έλεγχοι για τους αστεροειδείς (αλλά φυσικά μπορείτε να προσθέσετε επιπλέον ελέγχους αν το επιθυμείτε).

Άσκηση 3 (15%)

Στην άσκηση αυτή καλείστε να ολοκληρώσετε τη συνάρτηση state_update που υλοποιήσατε στην προηγούμενη άσκηση, προσθέτωντας τις παρακάτω λειτουργίες:

• Δημιουργία αστεροειδών: σε κάθε update πρέπει να υπάρχουν ASTEROID_NUM αστεροειδείς κοντά στο διαστημόπλοιο, όπου “κοντά” θεωρείται απόσταση έως ASTEROID_MAX_DIST. Αν δεν υπάρχουν τότε δημιουργούνται όσοι λείπουν, καλώντας τη συνάρτηση add_asteroids.

• Σφαίρες:

  • Πατώντας space δημιουργείται μια σφαίρα, αλλά μόνο αν έχουν περάσει τουλάχιστον BULLET_DELAY frames από την τελευταία σφαίρα.
  • Η σφαίρα έχει σχετική ταχύτητα BULLET_SPEED ως προς το διαστημόπλοιο, στην κατεύθυνση του διαστημοπλοίου. Δηλαδή στην ταχύτητα του διαστημοπλοίου προσθέτουμε το διάνυσμα που προκύπτει πολλαπλασιάζοντας με BULLET_SPEED το διάνυσμα κατεύθυνσης του διαστημοπλοίου.
  • Κάθε σφαίρα κινείται όπως όλα τα αντικείμενα χωρίς να μεταβάλλεται ποτέ η ταχύτητά της.

• Συγκρούσεις:

  • Αν το διαστημόπλοιο συγκρουστεί με αστεροειδή τότε ο αστεροειδής καταστρέφεται (και το σκορ μειώνεται όπως περιγράφεται παρακάτω).
  • Αν μια σφαίρα συγκρουστεί με αστεροειδή:
    • Ο αστεροειδής αφαιρείται και προστίθενται δύο νέεοι αστεροειδείς με το μισό μέγεθος από τον αρχικό
    • Οι νέοι αστεροειδείς πρέπει να είναι τουλάχιστον ASTEROID_MIN_SIZE σε μέγεθος, διαφορετικά δεν προστίθενται (απλά αφαιρείται ο αρχικός).
    • Η ταχύτητα των νέων αστεροειδών έχει τυχαία κατεύθυνση και μήκος 1,5 φορά μεγαλύτερο της ταχύτητας του αρχικού.

  Για τις συγκρούσεις μπορείτε να χρησιμοποιήσετε (χωρίς να είναι απαραίτητο) τη συνάρτηση CheckCollisionCircles από το libraylib.h.

• Σκορ:

  • Για κάθε νέο αστεροειδή που δημιουργείται το σκορ αυξάνεται κατά 1.
  • Για κάθε αστεροειδή που συγκρούεται με σφαίρα το σκορ μειώνεται κατά 10.
  • Αν το διαστημόπλοιο συγκρουστεί με αστεροειδή χάνεται το μισό σκορ.
  • Κάθε φορά που το σκορ φτάνει σε πολλαπλάσιο του 100 η ταχύτητα του παιχνιδιού γίνεται 10% μεγαλύτερη. Αυτό επιτυγχάνεται αυξάνοντας το speed_factor και φροντίζοντας όλες οι μετακινήσεις να λαμβάνουν υπόψη το speed_factor.

Τέλος, επεκτείνετε το tests/test_state.c ώστε να ελέγχει τις παραπάνω λειτουργίες. Όπως πάντα, δε χρειάζονται εξαντλητικά tests, αρκεί να ελέγχονται σύντομα οι συγκρούσεις και η κίνηση.

Άσκηση 4 (15%)

Υλοποιήστε ένα module set_utils.h με τις παρακάτω λειτουργίες:

// Επιστρέφει την μοναδική τιμή του set που είναι ισοδύναμη με value,
// ή αν δεν υπάρχει, την μικρότερη τιμή του set που είναι μεγαλύτερη
// από value. Αν δεν υπάρχει καμία τότε επιστρέφει NULL.

Pointer set_find_eq_or_greater(Set set, Pointer value);

// Επιστρέφει την μοναδική τιμή του set που είναι ισοδύναμη με value,
// ή αν δεν υπάρχει, την μεγαλύτερη τιμή του set που είναι μικρότερη
// από value. Αν δεν υπάρχει καμία τότε επιστρέφει NULL.

Pointer set_find_eq_or_smaller(Set set, Pointer value);

Η υλοποίηση πρέπει να είναι αποδοτική, χωρίς να διατρέχει ολόκληρο το set. Ένας γενικός τρόπος (που δεν απαιτεί γνώση της υλοποίησης του ADTSet) είναι ο εξής: πρώτα ελέγχετε αν το value υπάρχει ήδη. Αν όχι, τότε το εισάγετε, χρησιμοποιείτε το νέο στοιχείο για να βρείτε το αμέσως επόμενο/προηγούμενο, και τέλος το αφαιρείτε.

Επίσης υλοποιήστε ένα test που να ελέγχει (εν συντομία) την υλοποίηση του module.

Άσκηση 5 (20%)

Η υλοποίηση modules/state.c του module state.h που φτιάξατε στις προηγούμενες εργασίες είναι πολύ καλή για να δημιουργήσουμε ένα γρήγορο prototype του παιχνιδιού, αλλά η αποθήκευση δεδομένων στο Vector objects δημιουργεί σημαντική καθυστέρηση στους αλγορίθμους. Στην άσκηση αυτή καλείστε να φτιάξετε μια τροποποιημένη υλοποίηση modules/state_alt.c του ίδιου module, χρησιμοποιώντας οποιονδήποτε ADT είδαμε στο μάθημα, με τους παρακάτω στόχους:

• Η συνάρτηση state_objects πρέπει γρήγορα να επιστρέφει τα αντικείμενα που βρίσκονται ανάμεσα στα top_left και bottom_right, χωρίς να εξετάζει όλα τα αντικείμενα της πίστας.

• Η state_update πρέπει να ενημερώνει μόνο τα αντικείμενα που βρίσκονται σε απόσταση το πολύ 2 οθόνων από το διαστημόπλοιο (τα υπόλοιπα μπορούν να παραμένουν ακίνητα). Η εύρεση των αντικειμένων δεν πρέπει να εξετάζει όλα τα αντικείμενα της πίστας.

• Στην state_update, ο έλεγχος των συγκρούσεων πρέπει να είναι αποδοτικός χωρίς να εξετάζει όλα τα αντικείμενα της πίστας.

Για την υλοποίησή σας μπορείτε να τροποποιήσετε το state_alt.c όπως νομίζετε, αλλά καμία αλλαγή δεν επιτρέπεται στο state.h (ώστε οι χρήστες του module να συνεχίζουν να δουλεύουν χωρίς τροποποιήσεις). Η υλοποίησή σας θα πρέπει επίσης να περνάει το tests/state_test.c που έχετε φτιάξει στις προηγούμενες ασκήσεις, χωρίς καμία τροποποίηση.

Άσκηση 6 (15%)

Στο τελικό στάδιο είμαστε πλέον έτοιμοι να υλοποιήσουμε το πλήρες παιχνίδι. Για το σκοπό αυτό καλείστε να υλοποιήσετε ένα module interface.h με τις ακόλουθες συναρτήσεις.

// Αρχικοποιεί το interface του παιχνιδιού
void interface_init();

// Κλείνει το interface του παιχνιδιού
void interface_close();

// Σχεδιάζει ένα frame με την τωρινή κατάσταση του παιχνδιού
void interface_draw_frame(State state);

Η βασική συνάρτηση είναι η interface_draw_frame στην οποία πρέπει αρχικά να συλλέξετε πληροφορίες για την κατάσταση του παιχνιδιού, χρησιμοποιώντας το state.h module, και στη συνέχεια να σχεδιάσετε τα αντικείμενα τα οποία είναι ορατά στο συγκεκριμένο frame.

Για το σχεδιασμό μπορείτε να χρησιμοποιείτε όλες τις συναρτήσεις του raylib.h, δείτε το παράδειγμα του programs/game_example για να ξεκινήσετε. Πλήρης λίστα με τις συναρτήσεις υπάρχει στο raylib.h.

Φυσικά εσείς θα χρειαστείτε ελάχιστες από αυτές, δείτε κυρίως τις DrawLine, DrawText, DrawCircleLines, DrawTexture, .... Τα γραφικά δεν χρειάζεται προφανώς να είναι σύνθετα, μπορεί το κάθε αντικείμενο να είναι απλά ένας χρωματιστός κύκλος, αρκεί το τελικό αποτέλεσμα να είναι playable.

Προσοχή: στην οθόνη θέλετε να σχεδιάσετε μόνο το ορατό μέρος της συνολικής πίστας. Οπότε πρέπει να βρείτε τα αντικείμενα που είναι ορατά (μέσω της state_objects) αλλά και να μετατρέψετε τις συντεταγμένες του state σε συντεταγμένες της οθόνης.

Για να ολοκληρωθεί το παιχνίδι χρειάζεται τέλος και μία συνάρτηση main η οποία θα ξεκινάει το “main loop” του παιχνιδιού, καλώντας διαδοχικά τις state_update και interface_draw_frame. Και πάλι, δείτε το παράδειγμα του programs/game_example. Η συνάρτηση main πρέπει να βρίσκεται στο αρχείο programs/game/game.c.

Παρατηρήσεις: Το παιχνίδι θα πρέπει να δουλεύει και με τις δύο υλοποιήσεις του state.h module που υλοποιήσατε. Για να δείτε τη διαφορά στην απόδοση, προσθέστε ένα framerate (FPS) counter, και δοκιμάστε να προσθέσετε έναν μεγάλο αριθμό τυχαίων αντικειμένων μέχρι το FPS να πέσει κάτω από 60.

Επίσης, όπως αναφέρθηκε και στην Άσκηση 3, είστε ελεύθεροι να τροποποιήσετε την υλοποίηση του state.h module για να προσαρμόσετε το παιχνίδι στο interface που δημιουργήσατε. Στο interface του module από την άλλη δεν επιτρέπονται αλλαγές (αλλά έχετε πλήρη ελευθερία για αλλαγές στο παρακάτω design competition).

Design competition

Αφήστε τη δημιουργικότητά σας να δουλέψει και εξελίξτε το παιχνίδι με οποιοδήποτε τρόπο θέλετε! Βάλτε νέους χαρακτήρες, εξελίξτε το gameplay, φτιάξτε καλύτερα physics, βελτιώστε τα γραφικά, προσθέστε storyline, σχεδιάστε πίστες, animations, ή οτιδήποτε άλλο θέλετε.

Νικητής του διαγωνισμού θα είναι απλά το πιο ευχάριστο παιχνίδι. Αυτό δε σημαίνει το πιο σύνθετο τεχνικά, συχνά τα απλά παιχνίδια είναι και τα πιο εθιστικά. Η επιλογή θα γίνει με ψηφοφορία (ίσως μετά από προεπιλογή, αν οι συμμετοχές είναι πάρα πολλές). Όλοι οι συμμετέχοντες μπορούν να κερδίσουν bonus έως 25% στο βαθμό της εργασίας (ανάλογα με τις βελτιώσεις που έχουν υλοποιήσει), ενώ οι 2 πρώτοι κερδίζουν bonus 50% και 100% αντίστοιχα.

Για να συμμετέχετε στο διαγωνισμό, φτιάξτε το παιχνίδι σας στο directory programs/competition, και βεβαιωθείτε ότι τρέχοντας make game στο directory αυτό παράγεται το εκτελέσιμο game του παιχνιδιού. Τα περιεχόμενα του directory δε θα ληφθούν υπόψη στη βαθμολόγηση παρά μόνο στο διαγωνισμό. Για τις βελιτώσεις του παιχνιδιού έχετε προθεσμία μέχρι το deadline της δεύτερης εργασίας. Αλλαγές στo repository που θα γίνουν μετά την προθεσμία της πρώτης εργασίας, και πριν την προθεσμία της δεύτερης, θα ληφθούν υπόψη για τον διαγωνισμό αλλά όχι για τη βαθμολόγηση της εργασίας. Επίσης περιγράψτε τις βελτιώσεις που υλοποιήσατε στο README.md.

Χρήση σε Windows/WSL

Για να κάνετε compile το game_example σε WSL:

• Αρχικά ακολουθήστε τις οδηγίες εγκατάστασης και εκτελέστε το

  curl https://k08.chatzi.org/vscode/config.sh | bash
  

  (ίσως χρειαστεί να το ξανατρέξετε, αν δεν το έχετε κάνει πρόσφατα).

• Στη συνέχεια εγκαταστήστε το VcXsrv το οποίο επιτρέπει να τρέχουμε Linux προγράμματα με γραφικό interface στο WSL.

• Αφού το εγκαταστήσετε, εκτελέστε το VcXsrv, επιλέξτε τις default ρυθμίσεις, και κρατήστε το ανοικτό όσο δουλεύετε.

• Τέλος κάνουμε compile/debug από το VS Code ως συνήθως (Ctrl-Shift-B, F5, κλπ).

Αν θέλουμε να τρέξουμε το παιχνίδι manually από την κονσόλα, εκτελούμε πιο πριν export DISPLAY=:0 (το Makefile το κάνει αυτό αυτόματα).

Τρέχοντας το παιχνίδι μέσα από WSL δεν θα έχει ήχο, αλλά δεν είναι απαραίτητος ο ήχος για την εργασία. Οι πιο τολμηροί μπορούν να δοκιμάσουν τις παρακάτω οδηγίες για ήχο σε WSL (αλλά ίσως είναι απλούστερο απλά να χρησιμοποιήσετε Linux).

Τέλος το Makefile που σας δίνεται επιτρέπει να παράγετε και native executables (.exe) μέσα από το WSL, τα οποία υποστηρίζουν και ήχο:

sudo apt install gcc-mingw-w64-x86-64
make OS=Windows_NT