Complete Emberbound survival adventure and delivery pipeline

.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.{yml,yaml,svg}]
+indent_size = 2
+
+[*.cmd]
+end_of_line = crlf

.gitattributes

@@ -0,0 +1,10 @@
+* text=auto
+*.java text eol=lf
+*.md text eol=lf
+*.xml text eol=lf
+*.yml text eol=lf
+*.svg text eol=lf
+mvnw text eol=lf
+*.sh text eol=lf
+*.cmd text eol=crlf
+*.png binary

.github/dependabot.yml

@@ -0,0 +1,17 @@
+version: 2
+updates:
+  - package-ecosystem: maven
+    directory: /
+    schedule:
+      interval: monthly
+    open-pull-requests-limit: 5
+    groups:
+      build-and-test:
+        patterns: ['*']
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly
+    groups:
+      github-actions:
+        patterns: ['*']

.github/pull_request_template.md

@@ -0,0 +1,11 @@
+## Change
+
+Describe the behavior before and after this change, and why it matters.
+
+## Validation
+
+- [ ] `mvnw verify` passes (use `mvnw.cmd` on Windows).
+- [ ] Relevant gameplay or persistence regressions are covered.
+- [ ] Gameplay rules and documentation agree.
+
+Include a short transcript when changing the player experience.

.github/workflows/ci.yml

@@ -0,0 +1,59 @@
+name: Verify Emberbound
+
+on:
+  push:
+    branches: [master, main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: verify-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  verify:
+    name: Java 21 / ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+        with:
+          persist-credentials: false
+      - uses: actions/setup-java@de7274f081f381c8f8158605e0321c36c376e2e6 # v6
+        with:
+          distribution: temurin
+          java-version: '21'
+          cache: maven
+      - name: Verify on Linux
+        if: runner.os != 'Windows'
+        run: sh ./mvnw --batch-mode --no-transfer-progress verify
+      - name: Verify on Windows
+        if: runner.os == 'Windows'
+        run: .\mvnw.cmd --batch-mode --no-transfer-progress verify
+      - name: Play packaged demo
+        shell: bash
+        run: java -jar target/emberbound.jar --demo > target/demo.txt
+      - name: Upload executable and demo
+        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6
+        with:
+          name: emberbound-${{ runner.os }}
+          path: |
+            target/emberbound.jar
+            target/demo.txt
+          if-no-files-found: error
+      - name: Upload test and coverage reports
+        if: always()
+        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6
+        with:
+          name: reports-${{ runner.os }}
+          path: |
+            target/surefire-reports/
+            target/site/jacoco/
+          if-no-files-found: ignore

.gitignore

@@ -28,4 +28,10 @@ bin/
 .vscode/
 
 ### Mac OS ###
-.DS_Store
+.DS_Store
+
+### Maven / game saves ###
+target/
+.saves/
+*.class
+*.log

.mvn/wrapper/maven-wrapper.properties

@@ -0,0 +1,4 @@
+wrapperVersion=3.3.4
+distributionType=only-script
+distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.11/apache-maven-3.9.11-bin.zip
+distributionSha256Sum=0d7125e8c91097b36edb990ea5934e6c68b4440eef4ea96510a0f6815e7eeadb

CONTRIBUTING.md

@@ -0,0 +1,27 @@
+# Contributing to Emberbound
+
+Use JDK 21 or newer and the included Maven Wrapper. Import `pom.xml` into your IDE; the source root is `src/main/java` and the entry point is `dev.emberbound.Main`.
+
+## Local workflow
+
+```sh
+sh ./mvnw spotless:apply
+sh ./mvnw verify
+java -jar target/emberbound.jar --demo
+```
+
+On Windows replace `sh ./mvnw` with `.\mvnw.cmd`. If the shell's `java` points to an older installation, use the Java executable under `JAVA_HOME` or `play.cmd --demo`.
+
+## Making a change
+
+- Keep terminal output and file access out of `domain` and `engine`.
+- Add a behavior-focused regression test when changing combat, progression, economy or persistence. Use a fixed seed or explicit region populations.
+- Do not expose or depend on mutable internal progress maps.
+- Preserve the single-reader input model and graceful EOF behavior.
+- Treat save schema changes as compatibility changes: update the version and document migration or rejection behavior.
+- Keep gameplay documentation synchronized with balance and control changes.
+- Do not commit `target/`, IDE files or personal saves.
+
+The format is enforced by Spotless using Google Java Format's AOSP style. `verify` also enforces an 80% line-coverage floor and fails on compiler warnings. Test reports are under `target/surefire-reports`, with coverage at `target/site/jacoco/index.html`.
+
+Describe the observable behavior and the relevant validation in pull requests. For gameplay bugs, include your character, equipment, seed, actions and whether you loaded a save.

LICENSE

@@ -6,7 +6,7 @@ Copyright (c) 2024
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
 in the Software without restriction, including without limitation the rights
-to use, copy, modify, modify, merge, publish, distribute, sublicense, and/or sell
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the Software is furnished
 to do so, subject to the following conditions:
 

README.md

@@ -1,90 +1,124 @@
-# Currently under development...
+# Emberbound
 
-# Java Adventure Game
+![Emberbound — three supplies, one signal fire, a way home](docs/assets/emberbound.svg)
 
-![Java](https://img.shields.io/badge/Java-ED8B00?style=for-the-badge&logo=java&logoColor=white)
-![Platform](https://img.shields.io/badge/platform-JVM-blue?style=for-the-badge)
-![License](https://img.shields.io/github/license/cihat-kose/java-adventure-game?style=for-the-badge&cacheSeconds=60)
-![Last Commit](https://img.shields.io/github/last-commit/cihat-kose/java-adventure-game?style=for-the-badge)
+[![CI Tests](https://img.shields.io/github/actions/workflow/status/cihat-kose/java-adventure-game/ci.yml?branch=master&style=for-the-badge&label=CI%20Tests&logo=github)](https://github.com/cihat-kose/java-adventure-game/actions/workflows/ci.yml)
+[![Java 21](https://img.shields.io/badge/Java-21-ED8B00?style=for-the-badge&logo=openjdk&logoColor=white)](https://openjdk.org/projects/jdk/21/)
+[![Maven](https://img.shields.io/badge/Maven-C71A36?style=for-the-badge&logo=apachemaven&logoColor=white)](https://maven.apache.org/)
+[![JUnit 5](https://img.shields.io/badge/JUnit%205-25A162?style=for-the-badge&logo=junit5&logoColor=white)](https://docs.junit.org/5.13.4/user-guide/)
+[![MIT License](https://img.shields.io/badge/License-MIT-green?style=for-the-badge)](LICENSE)
 
-## 📖 Introduction
+A complete, turn-based survival adventure for the terminal. Explore a fog-bound island, survive its inhabitants, and gather **Food, Firewood and Water**. Bring them back to the Safe House to light a signal fire and escape.
 
-Welcome to **java-adventure-game**, a text-based adventure game currently under development. Built with Java, this game immerses players in a world filled with thrilling battles, quests, and choices. Prepare to face fierce enemies, gather resources, and explore multiple locations as you fight to survive and thrive.
+Built with **Java 21**, with a UI-independent rules engine, validated save files, and automated tests. The console is the first playable interface; the game rules can be reused by a future web application.
 
-## 🎮 Gameplay Overview
+[Play](#play) · [Game guide](docs/GAMEPLAY.md) · [Architecture](docs/ARCHITECTURE.md) · [Türkçe](docs/README.tr.md)
 
-In this adventure, players will navigate through various locations, encounter obstacles, and collect valuable items. The choices you make will determine your fate in this adventure world. Will you survive the wilderness?
+## Play
 
-## 🦸 Characters
+Install **JDK 21 or newer** and point `JAVA_HOME` to it. Maven is downloaded automatically by the included [Maven Wrapper](https://maven.apache.org/tools/wrapper/). The first build needs internet access; the packaged game runs offline.
 
-![Characters](images/characters.png)
+```sh
+git clone https://github.com/cihat-kose/java-adventure-game.git emberbound
+cd emberbound
+```
 
-Choose from a roster of unique characters, each with their strengths and skills to help you tackle obstacles and navigate through the game’s challenges.
+**Windows — PowerShell or Command Prompt**
 
-## 👾 Obstacles
+```powershell
+.\play.cmd
+```
 
-![Obstacles](images/obstacles.png)
+**macOS / Linux**
 
-Encounter a range of foes with unique traits and difficulties. Be prepared to engage in combat, as each location presents different challenges.
+```sh
+sh ./play.sh
+```
 
-## 🗡️ Weapons
+The launchers build the game and use the JDK in `JAVA_HOME`. They do not run the test suite; use `verify` below before contributing.
 
-![Weapons](images/weapons.png)
+**Just want to see it?** Add `--demo` to either launcher. It plays a complete expedition through the real game, with visible inputs and no save-file access:
 
-Equip yourself with a variety of weapons to enhance your combat abilities:
-- **Pistol**
-- **Sword**
-- **Rifle**
+```text
+  --- YOU ESCAPED ---
+  Food for the crossing. Water for the journey. Firewood for a signal.
+  A sail appears beyond the fog. Ada, you are going home.
+  Enemies defeated: 6 | Supplies: 3/3 | Gold: 46
+```
 
-## 🛡️ Armors
+Already built? Run `java -jar target/emberbound.jar` with Java 21+. Run `java -version` if you see `UnsupportedClassVersionError`; the launchers avoid a mismatched Java on your PATH when `JAVA_HOME` is set.
 
-![Armors](images/armors.png)
+## The expedition
 
-Protect yourself with armors ranging from **Light** to **Heavy**, each providing different levels of protection in battle:
-- **Light Armor**
-- **Medium Armor**
-- **Heavy Armor**
+| Place | What you will find |
+| --- | --- |
+| Safe House | Free healing; escape when all three supplies are collected |
+| Tool Store | Three weapon upgrades, three armor upgrades, and healing bandages |
+| Cave | 1–3 zombies guarding **Food** |
+| Forest | 1–3 vampires guarding **Firewood** |
+| River | 1–3 bears guarding **Water** |
 
-## 🗺️ Locations
+Choose Samurai, Archer, or Knight. Attack first, anticipate the counterattack, and retreat when the odds turn against you. Defeated enemies stay defeated; cleared regions cannot be farmed. Every class can finish the game using the starting resources and earned gold.
 
-Explore diverse locations, each offering different features, items, and foes to face:
+The journal tracks objectives. Save from the map, save and quit, or preserve a completed expedition at the ending. There is **no autosave**; a defeat leaves your previous checkpoint available.
 
-- **Safe House**
-  - **Feature**: Restores player health completely.
+```sh
+java -jar target/emberbound.jar --seed 7
+java -jar target/emberbound.jar --save .saves/second-expedition.properties
+java -jar target/emberbound.jar --demo
+java -jar target/emberbound.jar --help
+```
 
-- **Cave**
-  - **Obstacle**: Zombies (1-3)
-  - **Feature**: Combat encounters with a chance to loot.
-  - **Item**: Food
+The default slot is `.saves/expedition.properties`, relative to the working directory. A new save replaces that slot; use `--save` for separate expeditions. The launchers use the repository directory.
 
-- **Forest**
-  - **Obstacle**: Vampires (1-3)
-  - **Feature**: Combat encounters with a chance to loot.
-  - **Item**: Firewood
+## Engineering
 
-- **River**
-  - **Obstacle**: Bears (1-3)
-  - **Feature**: Combat encounters with a chance to loot.
-  - **Item**: Water
+| Concern | Implementation |
+| --- | --- |
+| Rules independent of presentation | Domain objects and the combat state machine contain no console or filesystem code |
+| Reproducibility | Seeded populations are generated once and preserved across saves and retreats |
+| Defensive state transitions | Health bounds, one-time rewards, equipment upgrades, explicit victory and defeat |
+| Persistence | Versioned UTF-8 text, bounded reads, full validation before loading, temporary-file replacement |
+| Input handling | A single line reader, retries for invalid input, graceful EOF at every prompt |
+| Verification | JUnit 5 scenarios, 300 seeded campaign runs, JaCoCo coverage gate, Spotless formatting |
+| Delivery | Executable JAR; GitHub Actions configured for Java 21 on Windows and Linux |
 
-- **Toolstore**
-  - **Feature**: Purchase items to aid in your journey.
-  - **Weapons Available**: Pistol, Sword, Rifle
-  - **Armors Available**: Light, Medium, Heavy
+Read the [architecture and tradeoffs](docs/ARCHITECTURE.md), including the path to a future frontend. This is a single-player Java application; it currently has no HTTP API, database, or browser client.
 
-## 🚧 Development Status
+## Build and verify
 
-The game is currently in development, with more features and improvements to come. Stay tuned for updates on new locations, items, and gameplay elements.
+```powershell
+# Windows
+.\mvnw.cmd verify
+.\mvnw.cmd spotless:apply
+```
 
-## 🤝 Contributing
+```sh
+# macOS / Linux
+sh ./mvnw verify
+sh ./mvnw spotless:apply
+```
 
-Contributions are welcome! If you're interested in contributing, please follow these steps:
-1. Fork the repository.
-2. Create a new branch (`git checkout -b feature-branch`).
-3. Commit your changes (`git commit -m 'Add new feature'`).
-4. Push to the branch (`git push origin feature-branch`).
-5. Create a Pull Request.
+`verify` compiles with warnings treated as errors, runs tests, checks formatting, builds `target/emberbound.jar`, and enforces **at least 80% line coverage**. The readable coverage report is at `target/site/jacoco/index.html`; test results are in `target/surefire-reports/`.
 
-## 📜 License
+Tests cover combat ordering, retreat, death, victory, purchase failures, corrupted saves, failed file replacement, input recovery, save/resume, and the complete console demo. Campaign tests exercise all three characters over 100 seeds each.
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+The CI workflow uploads the executable, demo transcript, and reports after a successful run. Its badge reflects published workflow runs, not local verification.
+
+## Project layout
+
+```text
+src/main/java/dev/emberbound/
+  Main.java           Entry point and command-line options
+  domain/             Characters, equipment, player and expedition state
+  engine/             Combat actions, outcomes and state transitions
+  cli/                Terminal navigation, presentation and demo
+  persistence/        Save boundary and validated file implementation
+src/test/java/dev/emberbound/
+docs/                 Gameplay, architecture and portfolio notes
+.github/workflows/    Cross-platform verification
+```
+
+The original character, enemy, weapon and armor statistics are retained. The initial prototype has been completed and reorganized around the Emberbound game identity; the existing repository URL is unchanged.
+
+Contributions: [CONTRIBUTING.md](CONTRIBUTING.md). Project presentation: [portfolio notes](docs/PORTFOLIO.md). Licensed under [MIT](LICENSE).