read me

README.MD

@@ -0,0 +1,114 @@
+# Millions
+
+A JavaFX-based stock trading game developed as an exam project for the course **IDATT2003 – Programming 2** at NTNU, spring 2026.
+
+The project is made by **Group 40**.
+
+---
+
+## About the project
+
+Millions is a single-player simulation game with a simple goal: earn as much money as possible. The player starts with a given amount of capital and a stock exchange (`Exchange`) full of stocks (`Stock`) with varying "fortune" a value that afects how much the stock price fluctuates from week to week. Time in the game is measured in weeks, and each week the market changes, creating new buying and selling opportunities.
+
+The game combines a realistic portfolio and transaction model with more playful elements like minigames and dashboards, making it both a technical programming exercise and something that is actually fun to play.
+
+## What you can do in the game
+
+- **Create a new game** – choose player name, starting capital, and which exchange to trade on.
+- **Buy and sell stocks** on the exchange through a market overview (`MarketView`).
+- **Track your portfolio** on a dashboard with graphs over net worth, cash, and stock holdings over time.
+- **Play minigames** tied to a chosen stock to influence the outcome:
+  - *Clicker* – click targets for points
+  - *Find Stock* – find the correct stock among several alternatives
+  - *Time Inputs* – time-based key preses
+- **View transaction history** week by week in a dedicated archive (`TransactionArchive`).
+- **Save and load games** – the entire game state (player, exchange, week, portfolio, transactions) can be saved to file and loaded again later.
+- **Adjust settings** – theme (light/dark via `ThemeManager`) and other preferences, both from the main menu and within an active game.
+- **Quit safely** – a dedicated quit dialog lets the player save before exiting.
+
+## Architecture
+
+The application is built around **MVC** (Model–View–Controller) combined with a **publish–subscribe** pattern for events:
+
+- `model/` – domain classes: `Player`, `Exchange`, `Stock`, `Portfolio`, `Share`, `Transaction`, `SaveGame`, and others. All business logic for buying/selling, price changes, and portfolio management lives here.
+- `view/` – JavaFX views organized per screen (`mainmenu`, `settings`, `creategame`, `playgame`, `ingame`) and per widget (`dashboard`, `market`, `transactions`, `stats`, `minigames`, `topbar`, `financialsummary`).
+- `controller/` – connects views to the model and translates user input into operations on the model.
+- `service/` – service layer for heavier operations: `SaveGameService`, `GameStateLoader`, `StockFileManager`/`StockFileParser`, calculators for purchases and sales, and the event system under `service/event/`.
+- `utils/` – helpers such as `Validator`, `ThemeManager`, and `ConfigValues`.
+
+`EventManager` together with the `EventType` enum is used to publish events (scene changes, loading of save files, updating the transaction list, etc.) so that views and controllers do not need direct dependencies on each other.
+
+## Technologies
+
+- **Java 25**
+- **JavaFX 25.0.1** for the GUI
+- **Maven** as the build system
+- **JUnit Jupiter 6.0.1** for unit tests
+- **TestFX 4.0.18** for JavaFX tests
+- **JaCoCo** for test coverage reports
+- **GitHub Actions** for CI (tests on push, build on release)
+
+## Building and running
+
+Prerequisites: JDK 25 and Maven installed.
+
+```bash
+# Run the application
+mvn javafx:run
+
+# Run tests
+mvn test
+
+# Generate a runnable JAR (ends up in target/ as …-shaded.jar)
+mvn package
+
+# Generate Javadoc
+mvn javadoc:javadoc
+```
+
+Main class: `edu.ntnu.idi.idatt2003.g40.mappe.Launcher`.
+
+## Project structure
+
+```
+Millions/
+├── Docs/                          # Use case diagram and other documentation
+├── pom.xml                        # Maven configuration
+├── src/
+│   ├── main/
+│   │   ├── java/edu/ntnu/idi/idatt2003/g40/mappe/
+│   │   │   ├── Launcher.java      # Entry point
+│   │   │   ├── Main.java          # JavaFX Application class
+│   │   │   ├── controller/
+│   │   │   ├── model/
+│   │   │   ├── service/
+│   │   │   │   └── event/         # Pub/sub event system
+│   │   │   ├── utils/
+│   │   │   └── view/
+│   │   │       ├── creategame/
+│   │   │       ├── ingame/
+│   │   │       ├── mainmenu/
+│   │   │       ├── playgame/
+│   │   │       ├── settings/
+│   │   │       └── widgets/       # DashBoard, Market, MiniGames, etc.
+│   │   └── resources/
+│   │       ├── Fonts/
+│   │       └── Icons/
+│   └── test/                      # JUnit and TestFX tests
+└── .github/workflows/             # CI pipelines
+```
+
+## Exam context
+
+This project is the submission for the IDATT2003 exam, spring 2026, and demonstrates:
+
+- object-oriented design with encapsulation, inheritance, and polymorphism
+- use of design patterns (MVC, Observer/Pub-Sub, Factory)
+- JavaFX GUI development with multiple views and reusable widgets
+- file I/O for saving and loading game state
+- unit and GUI testing
+- Maven-based project setup with CI
+
+## Authors
+
+Group 40, IDATT2003, NTNU – spring 2026.