Πηγαίος κώδικας παιχνιδιού mini golf: τρύπες, φυσική και χάρτης πίστας

Ο πηγαίος κώδικας παιχνιδιού mini golf κρίνεται σε μία εργασία: την προσθήκη τρύπας. Ένας αγοραστής που θέλει πίστα με μάρκα, εποχιακό επίπεδο ή το λογότυπο ενός πελάτη πάνω στο πράσινο θα ανοίξει πρώτα τα αρχεία των επιπέδων, και αν μια τρύπα είναι θαμμένη μέσα σε κώδικα μηχανής, το έργο κολλάει. Στο Puttide, το τρισδιάστατο mini golf μας, κάθε πίστα έχει δικό της αρχείο τρυπών σε απλή JavaScript, και το εγχειρίδιο περιγράφει την προσθήκη μιας.

Αυτός ο οδηγός ακολουθεί το πακέτο όπως το βλέπει ένας προγραμματιστής: οι φάκελοι, οι βιβλιοθήκες, τα αρχεία των πιστών, η σειρά των αλλαγών, η φιλοξενία και η άδεια. Τα ονόματα των αρχείων προέρχονται από τον οδηγό αγοραστή που συνοδεύει το παιχνίδι.

Η σύντομη απάντηση για όσους βιάζονται: το Puttide είναι μορφοποιημένη JavaScript, με Three.js για το σχέδιο και Rapier για τη φυσική της μπάλας, και τα δύο ενσωματωμένα. Χωρίς βήμα build, χωρίς CDN και χωρίς κώδικα διακομιστή.

Τι περιλαμβάνει ο πηγαίος κώδικας του παιχνιδιού mini golf

Το Puttide είναι ολοκληρωμένο παιχνίδι με 30 τρύπες σε πέντε νησιωτικές πίστες: Sunlit Ruins, Lantern Pier, Frost Peaks, Cloud Garden και Volcano Forge, από έξι τρύπες η καθεμία. Ράμπες, πύλες, μπάμπερ και ανεμόμυλοι κάνουν τις τρύπες μικρά παζλ. Κάθε τρύπα δίνει τρία αστέρια (τέρμα, par ή καλύτερα, το κρυμμένο νόμισμα), και τα χάλκινα, ασημένια και χρυσά μετάλλια ανταμείβουν τους καλύτερους γύρους.

Εκτός από τις πίστες, υπάρχει ημερήσια πρόκληση με ανατροπή (άνεμος, παγωμένο πράσινο, βαριά μπάλα, ελαστικοί τοίχοι, βροχή νομισμάτων ή κυνήγι birdie), ένα Locker (ντουλάπα) όπου τα νομίσματα αγοράζουν μπάλες, ίχνη και άλλα καλλυντικά, και γύροι για δύο έως τέσσερις παίκτες με σειρά σε μία συσκευή. Η διεπαφή έρχεται σε 14 γλώσσες.

• game/: το έτοιμο για ανέβασμα build, ο μόνος φάκελος που δημοσιεύετε.
• source/: το ίδιο παιχνίδι ως έκδοση για προγραμματιστές, με README και package.json.
• documentation/: ένας εικονογραφημένος οδηγός στα αγγλικά και τα πορτογαλικά.
• THIRD-PARTY-LICENSES/: κείμενα άδειας για τις βιβλιοθήκες και τις γραμματοσειρές.
• Έκδοση 1.1.0, ενημερωμένη στις 22 Οκτωβρίου 2026.

Ανοίξτε τη σελίδα του Puttide: demo, εγχειρίδιο και τιμή

Three.js, Rapier και το υπόλοιπο της στοίβας

Η μπάλα προσομοιώνεται από το Rapier 3D 0.21.0, που τρέχει ως WebAssembly, και η σκηνή σχεδιάζεται με το Three.js r186. Και τα δύο βρίσκονται στα lib/three/ και lib/rapier/ με τα αρχεία άδειάς τους, και το index.html έχει import map που δείχνει το παιχνίδι σε αυτά. Το εγχειρίδιο σημειώνει ότι τα αρχεία της βιβλιοθήκης δεν έχουν αλλάξει στη συμπεριφορά και έχουν μορφοποιηθεί μόνο ώστε να διαβάζονται.

Αυτό έχει σημασία για δύο λόγους. Πρώτον, τίποτα δεν φορτώνει από CDN, άρα ένας φορέας ή ένας πελάτης με αυστηρή πολιτική ασφαλείας χρειάζεται μόνο τον δικό του διακομιστή. Δεύτερον, η αναβάθμιση βιβλιοθήκης είναι χειροκίνητο, σκόπιμο βήμα: το source/package.json λέει τις ακριβείς εκδόσεις, και αντιγράφετε τα νέα αρχεία μονάδων πάνω στον αντίστοιχο φάκελο lib/ κρατώντας τις διαδρομές του import map.

• Three.js r186: άδεια MIT.
• Rapier 3D compat 0.21.0, με ενσωματωμένο WebAssembly: άδεια Apache-2.0.
• Γραμματοσειρές Rubik και Fredoka: SIL Open Font License 1.1.
• Δύο μουσικά κομμάτια: music/menu.mp3 και music/play-1.mp3.

Πού ζουν οι τρύπες, τα νομίσματα και τα κείμενα

Οι διαδρομές είναι ίδιες στο source/ και στο game/. Τα δεδομένα της πίστας χωρίζονται ανά νησί, κάτι που κρατά κάθε αρχείο αρκετά μικρό ώστε να διαβάζεται σε μία συνεδρία.

• src/course/courses.js: σειρά πιστών και απαιτήσεις ξεκλειδώματος.
• src/course/holes.js: οι τρύπες του Sunlit Ruins, με γεωμετρία, par και εμπόδια.
• src/course/pier.js, ice.js, lava.js και sky.js: οι τρύπες των άλλων τεσσάρων πιστών.
• src/sim/constants.js: ρύθμιση φυσικής.
• src/game/economy.js: μπάλες, ίχνη και στολές, με τις τιμές τους.
• src/ui/i18n.js και τα συνοδευτικά αρχεία του: τα λεξικά των 14 γλωσσών, με τα ονόματα των τρυπών και τις συμβουλές.
• src/game/localRecords.js: ρεκόρ πίστας που κρατιούνται στον browser.
• src/audio/audio.js: εφέ και αντιστοίχιση μουσικής, στο probeTracks.
• css/style.css: χρώματα διεπαφής, γραμματοσειρές και responsive στυλ.

Προσθήκη τρύπας, βήμα προς βήμα

Αυτή είναι η αλλαγή που κάνουν οι περισσότεροι αγοραστές, και το εγχειρίδιο την περιγράφει σε λίγες γραμμές. Την έχουμε αναλύσει στη σειρά που θα ακολουθούσαμε οι ίδιοι.

1. Διαλέξτε το αρχείο πίστας στο οποίο ανήκει η νέα τρύπα, για παράδειγμα το lava.js για το Volcano Forge.
2. Αντιγράψτε έναν υπάρχοντα ορισμό τρύπας που μοιάζει με αυτό που θέλετε.
3. Δώστε του ένα μοναδικό id. Η επαναχρησιμοποίηση id μπερδεύει την αποθηκευμένη πρόοδο.
4. Ορίστε το par, τη θέση του tee και τη θέση της τρύπας (cup), και μετά μετακινήστε ή αντικαταστήστε τα εμπόδια.
5. Προσθέστε την τρύπα στην πίστα της μέσα στο courses.js.
6. Προσθέστε το όνομα και τη συμβουλή της στα λεξικά γλωσσών, σε κάθε γλώσσα που παραδίδετε.
7. Παίξτε την: ελέγξτε τις συγκρούσεις, την ανάκτηση όταν η μπάλα βγαίνει εκτός πίστας και τα τρία αστέρια, με το κρυμμένο νόμισμα.

Επεξεργαστείτε στο source/, αντιγράψτε τα αλλαγμένα αρχεία στις ίδιες διαδρομές μέσα στο game/, και σερβίρετε τον φάκελο μέσω HTTP για δοκιμή. Το package.json έχει σενάριο serve, ή μπορείτε να τρέξετε python -m http.server 8765. Το Node.js είναι προαιρετικό και χρειάζεται μόνο αν θέλετε το npm να διαχειρίζεται τις εκδόσεις των βιβλιοθηκών.

Οι άλλες αλλαγές, με λογική σειρά

1. Μάρκα και χρώματα: λογότυπο, χρώματα και γραμματοσειρές στο css/style.css. Επιτρέπεται το white label, άρα η μάρκα σας μπορεί να αντικαταστήσει τη δική μας.
2. Τιμές στο Locker: economy.js. Φθηνότερα καλλυντικά κάνουν πιο φιλικό έναν casual ιστότοπο· ακριβότερα μακραίνουν μια μεγάλη καμπάνια.
3. Κείμενα: διατύπωση και συμβουλές στα αρχεία i18n.
4. Μουσική: τα δύο συμπεριλαμβανόμενα κομμάτια μπορούν να αντικατασταθούν με ηχογραφήσεις για τις οποίες έχετε άδεια. Αντιγράψτε το αρχείο και ενημερώστε τη ρητή αντιστοίχιση στο audio.js (probeTracks)· η μουσική σκηνών επιστρέφει στο κομμάτι του παιχνιδιού.
5. Φυσική: constants.js, τελευταία, και σε μικρά βήματα, γιατί κάθε τρύπα ρυθμίστηκε με τις τρέχουσες τιμές.

Για ένα συναφές έργο με την ίδια προσέγγιση απλής JavaScript και χωρίς καμία τρισδιάστατη βιβλιοθήκη, το πρότυπο μπιλιάρδου μας είναι χτισμένο με τον ίδιο τρόπο.

Velvet Pool: μπιλιάρδο 8-ball σε απλή JavaScript και WebGL2

Sunset Rally: τρισδιάστατο ping pong με καμπάνια εννέα αγώνων

Φιλοξενία, τύποι MIME και περιτύλιγμα εφαρμογής

Ανεβάστε όλα όσα είναι μέσα στο game/ σε φάκελο όπως public_html/puttide/, κρατήστε τους υποφακέλους, και ανοίξτε τη διεύθυνση μέσω HTTPS. Δεν χρειάζεται npm, PHP, βάση δεδομένων ή λογαριασμός στον διακομιστή. Το άνοιγμα του index.html από δίσκο δεν δουλεύει, γιατί οι browsers μπλοκάρουν τις μονάδες σε file://.

Το Puttide έχει μία λεπτομέρεια φιλοξενίας που δεν έχει ένα παιχνίδι 2D: η φυσική τρέχει ως WebAssembly. Ο διακομιστής σας πρέπει να στέλνει αρχεία .js με τύπο MIME JavaScript και .wasm ως application/wasm. Ένας φιλοξενητής που το κάνει λάθος δείχνει κενή οθόνη ή σφάλμα μονάδας, άρα ελέγξτε το από την πρώτη μέρα.

• Ο browser χρειάζεται: JavaScript, ES modules, WebAssembly και WebGL2.
• Σε iframe πύλης, επιτρέψτε πλήρη οθόνη και αυτόματη αναπαραγωγή.
• Σε οθόνες αφής: σύρετε για να σκοπεύσετε και να χτυπήσετε, δύο δάχτυλα για περιστροφή της κάμερας, τσίμπημα για ζουμ.
• Δεν είναι εγκαταστάσιμη εφαρμογή offline: κάθε νέα φόρτωση φτάνει ακόμη στον φιλοξενητή σας.

Τα έργα εγγενών εφαρμογών δεν περιλαμβάνονται στο πακέτο. Αν σχεδιάζετε κυκλοφορία σε κατάστημα, προϋπολογίστε το περιτύλιγμα και τη δοκιμή του σε πραγματικά τηλέφωνα, γιατί ένα τρισδιάστατο παιχνίδι με φυσική είναι βαρύτερο από ένα παιχνίδι με χαρτιά σε παλιές συσκευές.

Τι δεν περιλαμβάνεται, και η άδεια

Πρόκειται για την τοπική έκδοση για browser: χωρίς online multiplayer ή online δωμάτια, χωρίς online κατάταξη, χωρίς cloud λογαριασμούς, χωρίς SDK διαφημίσεων, χωρίς εγγενείς εφαρμογές και χωρίς φιλοξενία. Τα ρεκόρ πίστας, η ημερήσια πρόοδος και οι γύροι στην ίδια συσκευή μένουν στον browser του παίκτη, και καμία βαθμολογία δεν ανεβαίνει. Οι αποθηκεύσεις ανήκουν στην προέλευση του browser, άρα η μετακίνηση σε άλλον τομέα ξεκινά τους παίκτες από την αρχή.

Το Puttide κοστίζει 39 $· μέχρι τις 30 Νοεμβρίου 2026 η προσφορά Black Friday το φέρνει στα 33,15 $, και η αγορά δύο ή περισσότερων προτύπων σε μία παραγγελία προσθέτει έκπτωση πακέτου 5% έως 20%. Η άδεια είναι μόνιμη και μη αποκλειστική για ένα τελικό προϊόν, δικό σας ή ενός πελάτη. Μπορείτε να αλλάξετε τη μάρκα, τον κώδικα, τα γραφικά και τον ήχο, και να αφήσετε τους παίκτες να παίζουν δωρεάν ή με διαφημίσεις, αλλά δεν επιτρέπεται να μεταπωλήσετε το πρότυπο ή τον κώδικά του αυτούσιο. Η υποστήριξη διαρκεί έξι μήνες, ή δώδεκα με την επέκταση· οι προσαρμοσμένες τρύπες, οι ενσωματώσεις και η φιλοξενία προσφέρονται κατόπιν αιτήματος.

Όροι άδειας, υποστήριξης και επιστροφής, πλήρεις

Συχνές ερωτήσεις

Ο πηγαίος κώδικας του mini golf είναι σε TypeScript;

Όχι. Το Puttide είναι απλή, μορφοποιημένη JavaScript στα source/src και game/src, χωρίς δικά μας συμπιεσμένα ή ενσωματωμένα (bundled) αρχεία.

Μπορώ να προσθέσω δικές μου τρύπες ή πίστες;

Ναι. Αντιγράψτε μία τρύπα στο αρχείο της πίστας, δώστε ένα μοναδικό id, ορίστε par, tee και cup, προσθέστε την στο courses.js και προσθέστε το όνομα και τη συμβουλή της στα αρχεία γλωσσών.

Φορτώνει το Three.js από CDN;

Όχι. Το Three.js, το Rapier, οι γραμματοσειρές και η μουσική βρίσκονται όλα μέσα στο game/, άρα το παιχνίδι χρειάζεται μόνο τον φιλοξενητή σας.

Γιατί ο φιλοξενητής μου δείχνει κενή οθόνη;

Συνήθως για τους τύπους MIME. Σερβίρετε το .js ως JavaScript και το .wasm ως application/wasm, ανοίξτε το παιχνίδι μέσω HTTP(S), και ελέγξτε ότι είναι ενεργό το WebGL2.

Μπορούν να παίξουν φίλοι μαζί;

Ναι, δύο έως τέσσερις παίκτες παίζουν με σειρά στην ίδια συσκευή. Το online παιχνίδι δεν περιλαμβάνεται σε αυτή την έκδοση.

Είναι η σωστή βάση mini golf για εσάς;

Το Puttide ταιριάζει σε πύλη οικογένειας ή αθλητικών, σε γραφείο που χτίζει μια πίστα με μάρκα για έναν πελάτη, και σε προγραμματιστή που θέλει να δει πώς δουλεύουν μαζί το Three.js και το Rapier σε ευανάγνωστο κώδικα. Ταιριάζει λιγότερο σε έργο που χρειάζεται online γύρους ή κοινή κατάταξη από την πρώτη μέρα.

Παίξτε μια πλήρη πίστα στο demo σε τηλέφωνο, και μετά διαβάστε την ενότητα του εγχειριδίου για την προσθήκη τρύπας. Αν σας φαίνεται σαν απόγευμα δουλειάς, το υπόλοιπο παιχνίδι είναι ήδη χτισμένο.

Παίξτε το demo του Puttide και αγοράστε την άδεια