⚔️ City Wars: Tokyo Reign — JavaFX Edition

City Wars: Tokyo Reign is an advanced tactical card battle game built from the ground up as a comprehensive term project for the Object-Oriented Programming (OOP) course at Sharif University of Technology.

The project demonstrates clean OOP principles, design patterns, separation of concerns (MVC architecture), interactive graphical user interfaces (JavaFX + Scene Builder), persistent data management, real-time animation loops, and intelligent bot algorithms.

Originally engineered as a robust command-line interface (Phase 1) and subsequently transformed into an immersive, cyberpunk-themed desktop application (Phase 2), the game delivers strategic duel mechanics, multi-mode gameplay, an in-game card marketplace, player progression systems, and complete administrator capabilities.

• 21-Slot Dual-Track Board: Battle across parallel tracks with cards spanning customizable duration widths ($1$ to $5$ slots) and targeted lane placements [cite: 3, 4].
• Synergy & Character Buffs: Selecting one of the 4 specialized characters yields character-card type synergies, boosting Player Damage and providing strategic advantages [cite: 3, 4].
• Simultaneous Timeline Sweeper: Animated timeline sweeps sequentially across the board at the end of each combat round, resolving card clashes, dealing player damage, and dynamically recalculating HP bars in real-time [cite: 3, 4].
• Interactive Hit-Bar Mini-Game: Precision-based timing reflex bar (Progress/Ring indicator) triggers dynamically during combat, granting critical bonus damage when timed perfectly [cite: 3].
• Dynamic Board Destruction: Block destruction hazards, hole manipulation, and lane repair mechanics keep matches unpredictable [cite: 4].

• Secure Authentication: Regex validation, strong password requirements, math-based & ASCII-art noise CAPTCHAs, and security question password recovery [cite: 4].
• Brute-Force Defense: Exponential lock-out countdown penalty timer ($5 \times n$ seconds cooldown) upon repeated failed login attempts [cite: 3, 4].
• Progression System: Level-up curve, XP milestones, coin rewards, starter pack gifting ($20$ random cards upon first login), and dynamic maximum HP scaling [cite: 3, 4].
• Combat History & Leaderboard: Detailed match analytics (date, rival name, level, outcome, rewards/penalties) featuring pagination and multi-column sorting (date, win/loss, level, alphabetically) [cite: 3, 4].

• Deck Exploration: Live inventory categorized into Unlocked (owned) and Locked (available for purchase) cards with visual badges [cite: 1, 3].
• Multi-Tier Card Upgrades: Upgrade card stats (Attack, Defense, Duration, Player Damage) using accumulated coins, governed by player level prerequisites and compounding cost multipliers ($1.25\times$) [cite: 3, 4].

• Custom Card Creator: Add regular cards on the fly by defining custom attributes (Name, ATK/DEF values, Duration, Player Damage, Upgrade Level & Cost) [cite: 3, 4].
• Asset Uploader: Upload custom card artwork directly from local storage or select from curated cyberpunk asset presets [cite: 1, 3].
• Real-time Card Editing & Deletion: Live in-place attribute modification with input validation, plus safety confirmation dialogues for card deletion [cite: 3, 4].
• Player Analytics Monitor: Global player overview tracking user levels, wealth, and statistics [cite: 3, 4].

+-----------------------------------------------------------------------+
|                              GAME MODES                               |
+-------------------+-------------------+---------------+---------------+
| 👥 1v1 PvP Duel   | 💰 High-Stakes    | 🤖 Campaign   | 🛡️ Clan Wars  |
| Local turn-based  | Wager coin pots   | 5-Stage Story | Form clans,   |
| character battles | Winner takes all  | 4 Bots + Boss | group battles |
+-------------------+-------------------+---------------+---------------+

• Local hot-seat multiplayer where Player 2 logs into the match session [cite: 3, 4].
• Character selection screen with unique card decks and aesthetic profiles [cite: 3, 4].
• Flexible card placement controls: Drag-and-Drop, Click-to-Place, or Coordinate Text Input [cite: 1, 3].
• Automatic hand replenishment with guaranteed spell-to-attack card ratio balancing [cite: 4].

• Competitive mode requiring identical coin buy-in from both contenders [cite: 3, 4].
• Balance validation before match initiation [cite: 2, 4].
• Winner Takes All: The victor claims the entire consolidated coin pool upon victory [cite: 3, 4].

• Interactive Level Map: Visual stage roadmap tracking player progression through 5 distinct tiers [cite: 3].
• State Persistence (Save & Resume): Automatically saves campaign progress; players can return and Continue Last Game at any time [cite: 3, 4].
• Challenging AI Bots: 4 tiered AI opponents with contextual spell casting and placement heuristic algorithms [cite: 2, 4].
• Unique Boss Encounter: The final boss features a pre-filled, high-density card board. In each turn, rather than deploying cards, the boss randomly buffs two cards on its board while concealing individual card damage [cite: 3, 4].

• Clan creation, invitation code generation, and member management [cite: 4].
• Inter-clan group tournaments matching members in 1v1 duels, concluding with Clan Leader tie-breakers [cite: 2, 4].

Alongside standard combat units, specialized Spell Cards manipulate the field without consuming board duration [cite: 4]:

The project enforces clean separation of concerns and industry-standard Object-Oriented principles:

src/
├── model/                  # Pure Business Logic & Domain Entities
│   ├── auth/               # User, Admin, Security, Credentials
│   ├── card/               # Card (Normal/Spell), Deck, Character, CardType
│   ├── game/               # GameBoard, Block, RoundState, Timeline, HitBar
│   ├── campaign/           # LevelMap, BotAI, BossFight
│   └── economy/            # Shop, Inventory, Wallet, LevelManager
├── controller/             # Event Handlers & State Management
│   ├── AuthController.java
│   ├── MainMenuController.java
│   ├── BattleController.java
│   ├── ShopController.java
│   ├── AdminController.java
│   └── HistoryController.java
├── view/                   # JavaFX FXML Views & Styling
│   ├── fxml/               # Login, MainMenu, BattleArena, Shop, Admin, Map
│   ├── css/                # Cyberpunk theme stylesheets, Neon accents
│   └── assets/             # Card arts, Character sprites, SFX, BGM
└── util/                   # Helpers: CaptchaGenerator, DatabaseManager, SoundManager

• MVC (Model-View-Controller): Strict decoupling between graphical presentation (FXML/CSS), user input handling (Controllers), and game state rules (Models).
• Factory Pattern: Polymorphic creation of regular combat cards, special spells, and AI bot profiles.
• Strategy Pattern: Interchangeable decision-making behaviors for AI bots across campaign tiers.
• Observer Pattern: Event-driven UI updates for real-time timeline motion, HP reduction animations, and sound triggers.
• Singleton Pattern: Centralized management for SoundManager, DatabaseConnection, and CurrentSession.

• Java Development Kit (JDK): Version 17 or higher
• JavaFX SDK: Version 21+ (if not using Maven/Gradle plugins)
• Build Tool: Maven 3.8+ or Gradle 8.0+

git clone https://github.com/<your-username>/city-wars-tokyo-reign.git
cd city-wars-tokyo-reign

# Clean and run the JavaFX application
mvn clean javafx:run

# Run using Gradle wrapper
./gradlew run

• Adaptive Audio Engine: Dynamic background music (BGM) selector, sound effect volume control, and mute toggle [cite: 1, 3].
• Cyberpunk Aesthetics: Neon glows, dark-mode styling, dynamic progress indicators, and customizable UI themes [cite: 1, 3].
• Responsive Dialogs: Toast alerts, error tooltips, countdown overlays, and reward fanfare popups [cite: 3].

Developed as the Final Term Project for the Object-Oriented Programming (OOP) Course:

• Instructors: Dr. Hashemi, Dr. Vosooghi Vahdat [cite: 3, 4]
• Institution: Department of Computer Engineering, Sharif University of Technology [cite: 3, 4]