Solo Leveling - Text-Based Adventure Game

---

Project Structure

game (parent module)
├── domain        - Core business entities and models
│   ├── model     - Domain model classes
│   └── util      - Utility classes and helpers
├── service       - Business logic and application services
│   ├── spi       - Service Provider Interfaces (Filesystem, Save/Load, etc.)
│   └── world     - World management and game state
├── client        - User interface and presentation layer
│   ├── command   - Command parsing and handling
│   ├── controller - Controllers for application flow
│   ├── runtime   - Runtime and game loop
│   └── view      - UI/View components
└── resources     - Game data files (rooms, items, monsters, etc.)

Module Dependencies

• domain: No dependencies on other game modules (foundation layer)
• service: Depends on domain
• client: Depends on service and domain

---

Getting Started

To quickly set up the repo on your local machine for development, follow the steps below.

Mac OS / Linux

1. Install JDK 21 (Temurin recommended). java -version should show 21.x
2. Clone the repo: git clone ...
3. Run: ./gradlew --version # wrapper downloads Gradle
4. Run: ./gradlew spotlessApply clean check # build + tests + style checks
5. IntelliJ: Use the Gradle wrapper and set Gradle JVM = JDK 21.

Windows OS

1. Install Java 21 (Temurin): winget install EclipseAdoptium.Temurin.21.JDK. java -version should show 21.x
2. Clone the repo: git clone ...
3. Run: .\gradlew.bat --version
4. Run: .\gradlew.bat spotlessApply clean check

Notice that for Windows, the Gradle command will differ slightly. The rest of this document uses the command for Mac/Linux. If using Windows, just replace the ./gradlew with .\gradlew.bat unless if using Git Bash (recommended) or WSL2.

If using IntelliJ on Windows...

• File → Settings → Build Tools → Gradle → Gradle JVM → set to JDK 21
• EditorConfig support on (on by default)

---

Build + Format + Test

This project uses Spotless to auto-format your code. Code that does doe follow the formatting specifications cannot be committed to the repo. Refer to the config/checkstyle document for more information.

To auto-format your written code + build + test, run the following command in a terminal within the project's root:

./gradlew spotlessApply clean check

---

Daily Workflow

1. Sync and branch from development:

   git checkout development
   git pull origin development
   git checkout -b feature/<short-name>
   

2. Code + commit (follow commit/branch conventions detailed further below).
3. Before you push:

   ./gradlew spotlessApply clean check
   

4. Open a PR (Pull Request) → development. Fill the PR template. Fix any CI failures.
   • ./gradlew spotlessApply
   • ./gradlew clean check
5. Reviewer approves → merges to development.

Maintainers will periodically raise a PR from development → main for release/tags.

---

Branch & PR rules

• Branches:
  • main = always green, release-ready
  • development = integration branch
  • feature/<short-name> from development
• PRs:
  • Target development
  • Must pass CI (spotlessCheck, tests, Checkstyle)
  • Must be approved
  • Squash merge only
• Commit messages:
  • Conventional Commits (e.g., feat(parser): add verb synonyms)
  • Can also include ref number to specific card on tracking board (Trello or other? → TBD)

---

Formatting and Style

• Google Java Style is enforced by Spotless (same output on all machines).
  • Auto-format: ./gradlew spotlessApply (run this before every commit)
  • Check only: ./gradlew spotlessCheck
• Checkstyle (Google checks) catches naming/Javadoc/import rules that formatters don't.
  • Full pipeline: ./gradlew spotlessApply clean check
  • Reports (output):
    • Tests → build/reports/tests/test/index.html
    • Checkstyle → build/reports/checkstyle/main.html
    • Coverage → build/reports/jacoco/test/html/index.html

Google Checkstyle Guide: https://checkstyle.sourceforge.io/styleguides/google-java-style-20250426/javaguide.html

For Javadoc comments in code, refer to Google Checkstyle Guide: Javadoc.

---

How to Play the Game

Running the Game

Mac OS / Linux:

./gradlew run

Windows:

.\gradlew.bat run

The game will launch with a main menu where you can:

• [1] Start Game - Begin a new adventure
• [2] Load Game - Continue from a saved game
• [3] Help - View in-game help and commands
• [4] Exit - Quit the game

Running the JAR File

Alternatively, you can run the game using the generated JAR file located in build/libs/:

./gradlew clean build

Then run:

java -jar build/libs/game-<version>.jar

Game Features

• Exploration: Navigate through dungeons, discover rooms, and uncover secrets
• Combat: Battle monsters with attack, defend, and summon commands
• Puzzles: Solve various puzzles to unlock rewards and progress
• Inventory: Manage items, equipment, and artifacts
• Equipment: Equip weapons, armor, and artifacts to boost your stats
• Shadow Army: Recruit shadow allies and summon them in combat
• Auto-Save: Game automatically saves every 3 minutes
• Map System: View explored areas and navigate dungeons
• Multiple Saves: Up to 10 save slots

---

Complete Command Reference

Movement Commands

Command	Description	Example
go <direction>	Move in a direction (north/south/east/west/up/down)	go north
explore	Look around the current room	explore
map	View nearby explored areas	map
map full	View complete exploration map with room directory	map full

Direction Shortcuts:

• n, s, e, w, u, d - Quick shortcuts for directions

---

Combat Commands

Command	Description	Example
attack <monster>	Engage a monster in combat	attack iron-fanged lycan
defend	Block incoming attack (reduces damage)	defend
summon	Call upon Shadow Army to attack (if you have allies)	summon
ignore <monster>	Avoid fighting a creature	ignore high orc chief
run <monster>	Run away from a creature (same as ignore)	run gravemaw

Combat Tips:

• Summon deals damage based on: (50 + player_attack × 0.10) × ally_count
• Defend reduces incoming damage significantly
• Use ignore/run to avoid difficult fights

---

Inventory Commands

Command	Description	Example
inventory	View your items and equipment	inventory
pickup <item>	Take an item from the room	pickup frost sigil
drop <item>	Drop an item in current room	drop minor healing potion
use <item>	Use a consumable item	use minor healing potion
inspect <target>	Examine an item or monster	inspect demon king's crown
equip <item>	Equip weapon/armor/artifact	equip lich's staff
unequip <slot>	Remove equipped item (weapon/armor/artifact)	unequip weapon
activate <artifact>	Activate an artifact's passive power	activate demon king's crown

Inventory Tips:

• You can equip 1 weapon, 1 armor, and 1 artifact at a time
• Artifacts must be activated to grant passive bonuses
• Consumables restore health or provide temporary effects

---

Puzzle Commands

Command	Description	Example
solve <answer>	Answer an active puzzle	solve puzzle
hint	Get a hint for current puzzle	hint
ignore	Skip puzzle (no rewards)	ignore

Puzzle-Specific Commands (use when prompted):

• kneel statue, step rune, activate pillar, say arise, etc.
• embrace shadows / resist shadows (for destiny choice)
• input code (for code-based puzzles)

Puzzle Tips:

• Some puzzles require specific items in your inventory
• Failed attempts may result in instant death or lockout
• Ignoring a puzzle lets you bypass it but you get no rewards
• You can return to ignored puzzles later

---

System Commands

Command	Description	Example
help	Show available commands	help
stats	View character stats, equipment, allies	stats
save	Save your progress	save
load	View available save files	load
quit	Save and exit the game	quit

System Tips:

• Game auto-saves every 3 minutes
• Maximum of 10 save slots
• Save files are stored in ./saves/ directory
• Use main menu to load different save files

---

Testing

TODO: Testing strategy/implementation TBD, this will be updated.

• Build + tests + style: ./gradlew clean check
• Tests only: ./gradlew test
• Run tests + generate coverage report: ./gradlew test jacocoTestReport
• View coverage report: Open build/reports/jacoco/test/html/index.html in a browser.
• Run specific test class: ./gradlew test --tests "com.example.MyTestClass"
• Run specific test method: ./gradlew test --tests "com.example.MyTestClass.myTestMethod"

---

Pull Request (PR) Checklist

(what PR reviewers expect)

Also in tandem with PR template: .github/workflows/PULL_REQUEST_TEMPLATE.md

• Branch from development, PR to development
• Ran ./gradlew spotlessApply (auto-formatter)
• ./gradlew clean check passes locally
• Tests added/updated for new behavior
• Brief Javadoc comments included
• Docs updated if behavior/commands changed (/docs and/or README)
• No game data in views (MVC separation)
• Linked issues / milestone (e.g., "Fixes #123")

To mark an item as completed/checked when filling out the PR, replace space between brackets with "x" [x]

---

Git workflow

• Branches

  • main – release-only, protected.
  • development – integration branch. All feature/fix PRs target development.

• Merge policy

  • Use Merge commits. No rebase. No squash on protected branches.
  • Linear history is not required.

• Daily flow

  1. Sync development

     git switch dev
     git pull origin dev

  2. Start work

     git switch -c feat/<topic>   # or fix/<topic>

     If creating a branch based on an issue, you can copy/paste the issue from github using the "create branch" button available on the issue page (but add feat / chore / fix / etc. before the copied text). Example:

     git switch -c feat/19-implement-core-game-loop

  3. Commit small changes

     git add -A # adds all local changes
     git commit -m "feat: <what> <why>"

  4. Push and open PR → base=development

     git push origin feat/19-implement-core-game-loop

  5. Keep your branch up to date using merge

     git fetch origin
     git merge origin/dev   # resolve conflicts, commit, push

  6. After approval and green CI, click Merge in GitHub. Branch will automatically be deleted.

  7. Then switch back to development and pull latest changes:

     git switch dev
     git pull origin dev

• Release flow

  1. Open PR development → main when stable.
  2. Ensure CHANGELOG or Release Notes are updated.
  3. Click Merge. CI must pass.

• Commit and PR rules

  • Link issues: “Fixes #123”.
  • Keep PRs focused. Prefer < ~500 lines changed.
  • Run CI locally before pushing:

    ./gradlew spotlessApply clean check

Local Git hooks (automatic pre-commit checks)

Hooks in .githooks/ so everyone shares the same checks.

What runs on commit

• pre-commit: formats code with Spotless and runs ./gradlew clean check. The commit is blocked if checks fail.

One-time setup after cloning

• Mac/Linux or Git Bash:

  git config core.hooksPath .githooks
  chmod +x .githooks/pre-commit || true

• Windows (Command Prompt):

  git config core.hooksPath .githooks

Verify it's active

  git config --get core.hooksPath   # should print .githooks

Skip when needed (rare or never)

• One commit only:

    git commit --no-verify

Conflict resolution (quick guide)

git merge origin/dev
# edit files to resolve conflicts
git add <resolved files>
git commit # completes the merge
git push

---

Never open PRs from main → development.

• Edit PR → change base to development

Conventional branch names for non-feature changes → use: chore/docs/fix/hot-fix / test / refactor prefixes.

• Features: feature/<short-slug>
  • Example: feature/combat-parser
• Bug fixes (normal): fix/<tracker-id>-<short-slug>
  • Examples: fix/trello-42-null-save, fix/13-map-content-loader
• Hotfixes (urgent bugs in main): hotfix/<version>-<short-slug>
  • Example: hotfix/1.0.1-npe-on-start
• Chores / Docs / Refactors / Tests:
  • chore/<slug>, docs/<slug>, refactor/<slug>, test/<slug>

Use conventional commit messages: fix: ..., feat: ..., chore: ..., docs: ..., etc.

---

Quick workflows

Fix a bug on development (example):

# get the latest code from the dev branch
git checkout dev && git pull
# create a new branch for the issue/bug/fix
git checkout -b fix/trello-42-null-save
# code + tests + commit your work
# "Trello-42" would be the id of the appropriate Trello card
git add -A && git commit -m "fix(save): handle null save slots (Trello-42)"
git push -u origin fix/trello-42-null-save
# then open a PR to dev

Hotfix on main, then back into development (example):

In most cases, bugs will be fixed on the dev branch using the previous workflow above. The workflow below is for extreme cases only and will be coordinated by maintainers.

git checkout main && git pull
git checkout -b hotfix/1.0.1-npe-on-start
# code + tests + commit work
git commit -m "fix(startup): prevent NPE on empty args"
git push -u origin hotfix/1.0.1-npe-on-start
# PR to main, merge, tag v1.0.1, then:
git checkout dev && git pull
git merge origin/main
git push

---

Maintainers

Releasing (tags trigger the release workflow)

# Open a PR from dev -> main in GitHub, get approvals, merge
# After merging dev -> main
git checkout main
git pull

# Choose next version (tag a release). Examples:
# v0.2.0 = playable prototype, v1.0.0 = final
git tag -a v0.2.0 -m "Playable prototype"
git push origin v0.2.0

CI will build and attach the JAR to the tag's release. At the time of writing this, a baseline/skeleton "Scaffold only" exists (Pre-release, v0.1.0).

Versioning and tags

• Patch: vX.Y.Z for small fixes
• Minor: bump (increment) Y for meaningful features/milestones (prototypes → feature complete).
• Major: v1.0.0 for final submission.

---

Troubleshooting

• Gradle not executable: chmod +x gradlew (Mac/Linux).
  • Windows users must have gradlew.bat on PATH (it is in repo root).
• "Gradle 9 / deprecated" messages: Make sure you run ./gradlew ... (wrapper), not gradle ...
• If pre-commit hooks don’t fire, re-run git config core.hooksPath .githooks
• Wrong Java version: Set Project SDK/Gradle JVM to 21 in your IDE

  java -version should show 21.x

• Formatting fails in CI: run ./gradlew spotlessApply, then ./gradlew clean check, then re-commit.
• Checkstyle errors: open build/report/checkstyle/main.html to see the exact rule and file/line.
• Still having issues? Kill the running daemons and try again:

  ./gradlew --stop
  rm -rf build .gradle
  ./gradlew clean check

• Undo local changes: git checkout -- . (warning: discards uncommitted changes)
• Delete local branch: git branch -D <branch-name>
• Sync local branch with remote: git fetch origin then git reset --hard origin/<branch-name> (warning: discards uncommitted changes)
• Undo last commit but keep changes staged: git reset --soft HEAD~1 (useful if you forgot to run spotlessApply before committing or want to change commit message) You can always reach out to team members for troubleshooting help and questions via our Discord server (any channel, will update this when appropriate/specific channels are completely set up).

Any and all questions/requests welcomed.

---

What goes where

• Code: src/main/java/...
• Tests: src/test/java/...
• Docs: /docs (gameplay spec, architecture, test plan, release notes)
• Config: .editorconfig, Spotless/Checkstyle are in build.gradle (Google style)

---

Expectations

• Keep PRs small (easy to review)
• Address PR review comments.
• If you're blocked by something, ask for help early (label PR/Issue status:blocked, add comments, ping on Discord).

---