🌑 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.”