Banana Republic

Banana Republic adalah game strategi berbasis JavaFX untuk Tugas Besar 2 IF2010 Pemrograman Berorientasi Objek. Game ini mengadaptasi mekanik board game resource management: pemain mengumpulkan resource, melakukan trade, membangun pipe/settlement/laboratory, memainkan kartu eksperimen, menghindari efek robber, dan mengejar victory point.

Fitur Utama

• GUI JavaFX dengan main menu, lobby, game board, dialog trade, dialog card, robber, save/load, settings, dan result screen.
• Mode 3-4 pemain dengan kombinasi human player dan bot.
• Setup round, resource gathering, trade/build phase, robber discard/move/steal, dan game over phase.
• Dice roll dan produksi resource berdasarkan tile board.
• Domestic trade antar pemain, domestic trade langsung dengan bot jika bot memiliki resource yang diminta, dan maritime/bank trade.
• Build pipe, settlement, upgrade laboratory, longest road, largest army, dan victory point.
• Experiment card bawaan dan plugin card.
• Plugin runtime untuk map generator, bot strategy, dan experiment card.
• Save/load game ke file JSON, termasuk data plugin yang sedang digunakan.
• Audio BGM dan SFX melalui JavaFX Media.
• Unit, integration, UI smoke, architecture, dan resource test.

Prasyarat

• JDK 21.0.11, sesuai java-version.txt.
• Apache Maven.
• Environment yang dapat menjalankan JavaFX GUI.

Catatan:

• Untuk development normal, tidak perlu mengunduh JavaFX SDK manual. JavaFX sudah dideklarasikan sebagai dependency Maven.
• Untuk menjalankan GUI di WSL, pastikan WSLg/display server aktif. Untuk audio di WSL, pastikan audio host sudah tersedia; jika paplay bisa memutar suara tetapi aplikasi tidak, cek konfigurasi JavaFX Media/PulseAudio/PipeWire.

Struktur Project

.
|-- pom.xml
|-- java-version.txt
|-- src/main/java/org/bananarepublic
|   |-- core/           # Game engine, phase, state, turn, victory, player factory
|   |-- service/        # Build, trade, resource production, robber, card, bot turn
|   |-- model/          # Board, player, resource, building, card
|   |-- persistence/    # Save/load JSON mapper dan service
|   |-- plugin/         # Plugin API, loader, bot strategy bawaan
|   |-- audio/          # Audio engine/service/effect
|   `-- ui/             # JavaFX scene manager, controller, component
|-- src/main/resources
|   |-- fxml/
|   |-- images/
|   |-- styles/
|   `-- audio/
|-- src/test/java/org/bananarepublic
`-- plugins/           # Sample plugin projects

Menjalankan Aplikasi

Jalankan dari root repository:

mvn javafx:run

Command tersebut menggunakan javafx-maven-plugin dengan main class:

org.bananarepublic.ui.App

Build Runnable JAR

Buat JAR aplikasi:

mvn package

Output utama:

target/banana-republic.jar

Jalankan JAR:

java -jar target/banana-republic.jar

JAR ini dibuat menggunakan maven-shade-plugin dan memasukkan dependency JavaFX Linux untuk distribusi Linux/WSL. Untuk development lintas OS, mvn javafx:run tetap menjadi cara paling aman.

Menjalankan Test

Jalankan seluruh test:

mvn test

Test JavaFX sudah dikonfigurasi headless melalui maven-surefire-plugin, sehingga tidak perlu menambahkan flag TestFX secara manual untuk workflow normal.

Untuk menjalankan subset test:

mvn -Dtest=TradeFlowTest,TradeServiceTest test

Code Quality

Format kode otomatis:

mvn spotless:apply

Cek format:

mvn spotless:check

Jalankan Checkstyle:

mvn checkstyle:check

Cek lengkap sebelum push:

mvn spotless:check checkstyle:check test

Build sampai packaging:

mvn verify

Git Hook Lokal

Repository menyediakan pre-commit hook di .githooks/pre-commit.

Aktifkan dengan:

git config core.hooksPath .githooks
chmod +x .githooks/pre-commit

Setelah aktif, setiap commit akan menjalankan:

mvn -B spotless:check checkstyle:check test

Jika hook gagal hanya karena format, jalankan:

mvn spotless:apply

CI

Workflow GitHub Actions berada di:

.github/workflows/ci.yml

CI berjalan pada setiap push dan pada pull_request ke main. Tahap yang dijalankan:

1. Checkout repository.
2. Setup Java Temurin 21.0.11.
3. mvn -B spotless:check.
4. mvn -B checkstyle:check.
5. mvn -B install -DskipTests.
6. mvn -B -f plugins/pom.xml package.
7. mvn -B test.

Plugin

Project mendukung tiga jenis plugin:

• MapGeneratorPlugin untuk map custom.
• PlayerStrategy untuk bot custom.
• ExperimentCard untuk kartu eksperimen custom.

Build sample plugin:

mvn install -DskipTests
mvn -f plugins/pom.xml package

Output sample plugin:

plugins/banana-grant-card/target/banana-grant-card-1.0-SNAPSHOT.jar
plugins/volcano-island-map/target/volcano-island-map-1.0-SNAPSHOT.jar
plugins/aggressive-bot/target/aggressive-bot-1.0-SNAPSHOT.jar

Class name sample plugin:

Plugin	Class Name	Tipe
Banana Grant Card	org.bananarepublic.plugins.BananaGrantCard	ExperimentCard
Volcano Island Map	org.bananarepublic.plugins.VolcanoIslandMapGenerator	MapGeneratorPlugin
Aggressive Bot	org.bananarepublic.plugins.AggressiveBotStrategy	PlayerStrategy

Map plugin dan bot plugin dapat dimuat dari lobby sebelum game dimulai. Card plugin dapat dimuat dari Settings & Plugins saat game berjalan.

Save dan Load

Game dapat disimpan ke file JSON melalui tombol Save atau dialog Settings & Plugins. Load dilakukan dari menu/setting dengan memilih file save JSON.

Save data menyimpan:

• fase game dan pemain aktif,
• board, bangunan, robber, dan timer,
• inventory pemain,
• bank dan deck,
• plugin yang diperlukan untuk me-restore game.

Jika save menggunakan plugin, JAR plugin tersebut harus tetap tersedia di path yang tersimpan agar load dapat berhasil.

Assertion

Kode produksi menggunakan Java assert sebagai pengecekan invariant internal, terutama pada build, trade, resource production, robber, longest road, bank, game engine, dan save/load mapper. Assertion bukan pengganti validasi input; validasi utama tetap menggunakan exception.

Jika ingin menjalankan aplikasi dengan assertion aktif:

java -ea -jar target/banana-republic.jar

Jika program gagal saat -ea aktif, itu biasanya menandakan invariant internal dilanggar dan perlu diperiksa sebagai bug logika.

Troubleshooting

Java version tidak sesuai

Pastikan java -version menggunakan JDK 21.0.11 atau Java 21 yang kompatibel.

JavaFX tidak muncul di WSL

Pastikan WSLg atau display server sudah aktif. Jalankan dari terminal yang memiliki akses display GUI.

Audio tidak terdengar di WSL

Pastikan audio host WSL berjalan. Jika paplay dapat memutar audio tetapi aplikasi tidak, cek dependency JavaFX Media dan konfigurasi PulseAudio/PipeWire.

Plugin gagal diload

Pastikan:

• file JAR plugin ada,
• class name lengkap benar,
• plugin mengimplementasikan tipe yang diminta,
• main project sudah di-install ke local Maven repository sebelum build sample plugin.

Save gagal diload

Pastikan file save masih valid dan plugin yang direferensikan save file masih tersedia di path yang sama.