Skip to content

README.md

Latest commit

 

History

History
201 lines (145 loc) · 7.65 KB

README.md

File metadata and controls

201 lines (145 loc) · 7.65 KB

🌑 Eclipse – A Race Against Time to Survive Shifting Trials

“When the sun was devoured by an endless eclipse, the world plunged into chaos.
Only those who can conquer time itself may bring back the light.”

🎮 Introduction

Eclipse is a story-driven console adventure game built in Java, where you step into a world swallowed by eternal darkness.
You must face a series of Trials — fast-paced, time-bound mini-games that test your logic, speed, and reflexes.
Each decision counts, every second matters.

The project beautifully blends gameplay and code, demonstrating advanced Java concepts such as:

  • 🧱 Inheritance & Polymorphism
  • ⚙️ Abstract Classes & Interfaces
  • 🚨 Custom Exception Handling
  • 💾 File Handling & Serialization
  • ⏱️ Multithreading & Concurrency

🧩 Project Overview

“Eclipse – A Race Against Time” isn’t just a game — it’s a simulation of survival under pressure.
Each trial pushes you to think and act fast. The game keeps track of your progress, saves your state,
and challenges you with increasing difficulty.

When you start, a short interactive story unfolds line by line, building tension and atmosphere.
Then, the Game Engine takes over — setting the stage for a timed showdown between logic and instinct.

🗂️ Project Structure

The game follows a clean modular architecture, keeping logic and functionality neatly separated.

eclipsegame/
│
├── engine/                      # Core game engine and logic
│   ├── Main.java                # Entry point; shows story and starts engine
│   ├── GameEngine.java          # Controls game flow and manages trials
│   ├── TrialThread.java         # Runs each trial in a separate thread
│
├── exceptions/                  # Custom exception classes
│   ├── InvalidInputException.java
│   
│
├── trials/                      # All mini-games or "trials"
│   ├── MazeRunner.java          # Navigate through a maze before time runs out
│   ├── SpeedTrial.java          # Reflex-based challenge under pressure
│   ├── PuzzleTrial.java         # Logical puzzle for sharp minds
│   And many more 
|
├── utils/                       # Reusable helper utilities
│   ├── TimerThread.java         # Runs countdown timers
│   ├── Utils.java               # Handles and performs safe input validation
│   
│
├── gamestate.ser                # Serialized saved game data
├── scores.txt                   # Stores player performance scores

⚙️ How It All Works (Workflow)

Here’s the full game flow from launch to completion:

  1. The Story Begins –
    Main.java introduces the backstory, printing dramatic lines with subtle delays.

  2. The Game Engine Activates –
    GameEngine.startGame() loads progress and sets up the available Trials.

  3. Choosing a Trial –
    The player selects a mini-game from options like MazeRunner, SpeedTrial, or PuzzleTrial and many more.

  4. Running the Game –

    • A TrialThread executes the chosen game logic.
    • At the same time, a TimerThread starts ticking in the background.

  5. During Gameplay –

    • Player inputs are validated using Utils.
    • Invalid moves trigger InvalidInputException.

  6. Saving and Scoring –

    • Progress is written into gamestate.ser.
    • Results and performance scores are appended to scores.txt.

  7. End of the Game –
    A narrative closing message reflects your performance — victory, defeat, or survival.

🔗 How Files & Classes Connect

From To What Happens
Main.java GameEngine.java Starts the game flow after displaying the intro
GameEngine Trials Loads and executes each trial dynamically
GameEngine TrialThread Runs each trial concurrently with timer
TrialThread TimerThread Enforces countdown and time-based logic
GameEngine scores.txt, gamestate.ser Saves scores and progress
Utils Exceptions Validates and reports invalid user actions

🧠 Java Concepts Showcased

Concept Description
Inheritance & Polymorphism All Trials extend the abstract Trial class
Abstract Classes Common trial behavior defined in Trial
Custom Exceptions Gracefully handle timeouts and invalid inputs
File Handling Persistent storage for scores and state
Multithreading Parallel execution of trials and timers
Serialization Save and restore player progress seamlessly

📜 Method Reference

Method Defined In Purpose
main() Main.java Displays story and starts engine
startGame() GameEngine.java Sets up and manages the game
run() TrialThread.java Runs a trial in a new thread
run() TimerThread.java Handles the countdown
playTrial() Trial.java Abstract method every trial must define
validateInput() InputValidator.java Ensures safe player input
saveGame() FileHandler.java Serializes game progress
loadGame() FileHandler.java Loads previous game data
writeScore() FileHandler.java Records player scores
MazeRunner.playTrial() MazeRunner.java Implements maze challenge logic
SpeedTrial.playTrial() SpeedTrial.java Handles reaction game
PuzzleTrial.playTrial() PuzzleTrial.java Handles logic-based puzzle

🚨 Exception Handling in Action

Eclipse is built to be resilient and immersive even when errors occur.

Exception Trigger What It Does
InvalidInputException User enters invalid choice Displays warning & reprompts
TimeOutException Timer runs out Ends trial with time-up message
IOException File access issue Prevents crash during read/write
ClassNotFoundException Deserialization failure Gracefully handles corrupted saves

⏱️ Multithreading Design

The game creates a real-time sense of urgency using threads:

  • TimerThread counts down seconds independently.
  • TrialThread runs the trial logic concurrently.
  • Both threads communicate to ensure smooth endings — whether by success or timeout.

This design keeps the console experience alive, interactive, and suspenseful.

💾 File Handling & Serialization

The FileHandler class ensures progress and scores are persistent.

File Purpose
scores.txt Stores player results and ranks
gamestate.ser Serialized object holding progress and trial completion

If the player exits mid-game, their exact state can be restored later — thanks to Java’s ObjectOutputStream and ObjectInputStream.

🏁 Conclusion

“Eclipse – A Race Against Time” is more than a console game — it’s a complete demonstration of how storytelling and programming can intertwine.
It showcases your mastery of Object-Oriented Design, Threading, Exception Handling, and File Management — all within a clean, immersive experience.

Whether used for a project showcase or academic presentation, this game reflects deep conceptual understanding and creative execution.

📘 Resources & Technologies

  • Java SE 17+
  • VS Code (Java Extension Pack)
  • Java Collections Framework
  • Java IO and Serialization APIs
  • Multithreading (Thread & Runnable interfaces)
  • Custom Exception Design Patterns

💡 “In the darkness of the eclipse, your logic becomes your only light.”