🏰 Dungeon Crawler

A text-based dungeon crawler game built with PHP.

📖 Table of Contents

• Features
• Quick Start
• Installation
• How to Play
• Development
  • Project Structure
  • Git Workflow
  • Testing
  • Code Quality
• Architecture
  • C4 Container Diagram
  • Gameplay Flow Diagram
• CI/CD Pipeline
• Project Status
• Troubleshooting
• License

✨ Features

Core Gameplay

• 🎮 Turn-based combat - Strategic battles with monsters
• 🗺️ Dungeon exploration - Navigate through interconnected rooms
• ⚔️ Combat system - Fight monsters with calculated damage
• 💎 Treasure collection - Find valuable items in the dungeon
• 💾 Save/Load system - Persist your game progress
• 🏆 Win conditions - Find the exit to escape the dungeon

Technical Features

• 🏗️ Domain-Driven Design - Clean architecture with clear separation of concerns
• 🧪 Full test coverage - Unit and integration tests
• 🔄 CI/CD Pipeline - Automated testing and code quality checks
• 📊 Code quality tools - PHPStan, PHP CS Fixer, CodeSniffer
• 📝 Comprehensive documentation - Code comments and architectural decisions

🚀 Quick Start

# Clone the repository
git clone https://github.com/TooCodeSavvy/dungeon-crawler.git
cd dungeon-crawler

# Install dependencies
composer install

# Run the game
composer game

# Run tests
composer test

📦 Installation

Prerequisites

• PHP 8.4 or higher
• Composer 2.8.6
• Git

Detailed Installation

1. Clone the repository

   git clone https://github.com/TooCodeSavvy/dungeon-crawler.git
   cd dungeon-crawler

2. Install dependencies

   composer install

3. Verify installation

   # Run tests to ensure everything works
   composer test
   
   # Check code quality
   composer check

4. Start the game

   composer game

Commands

Command	Description	Example
Movement Commands
north, n	Move north	> north
south, s	Move south	> south
east, e	Move east	> east
west, w	Move west	> west
move <direction>	Alternative movement command	> move north
Combat Commands
attack, a	Attack monster	> attack
attack <target>	Attack specific monster	> attack goblin
flee	Try to escape from combat	> flee
Item Commands
take, get	Take all items in room	> take
take <item>	Take specific item	> take potion
use <item>	Use consumable item	> use health potion
equip <weapon>	Equip a weapon	> equip excalibur
Information Commands
map, m	Display dungeon map	> map
inventory, i, inv	Check inventory	> inventory
Game Management
save	Save current game	> save
help, h	Show help	> help
quit, q, exit	Exit game	> quit

Game Objectives

1. Explore the dungeon by moving between rooms
2. Fight monsters you encounter
3. Collect treasure for points
4. Find the exit to win
5. Survive - if your health reaches 0, you lose!

🛠️ Development

Project Structure

dungeon-crawler/
├── src/                      # Source code
│   ├── Domain/              # Core business logic
│   │   ├── Entity/         # Game entities (Player, Monster, Room)
│   │   ├── ValueObject/    # Value objects (Health, Position)
│   │   ├── Service/        # Domain services (Combat, Movement)
│   │   └── Repository/     # Repository interfaces
│   ├── Application/         # Application layer
│   │   ├── Command/        # Game commands
│   │   ├── State/          # State management
│   │   └── GameEngine.php # Main game loop
│   ├── Infrastructure/      # External concerns
│   │   ├── Persistence/    # Save/Load implementation
│   │   └── Console/        # CLI handling
│   └── Presentation/        # User interface
│       └── game.php        # Entry point
├── tests/                   # Test suites
│   ├── Unit/               # Unit tests
│   ├── Integration/        # Integration tests
│   └── Feature/            # Feature tests
├── docs/                    # Documentation
├── scripts/                 # Utility scripts
└── storage/                 # Game saves

Testing

Running Tests

# Run all tests
composer test

# Run specific test suites
composer test-unit          # Unit tests only
composer test-integration   # Integration tests only

# Run with coverage
composer test-coverage      # HTML report
composer test-coverage-text # Terminal output

# Run specific test file
composer test -- tests/Unit/Domain/ValueObject/HealthTest.php

# Run tests with filter
composer test -- --filter testHealthCannotGoNegative

Code Quality

Available Commands

# Check code style (PSR-12)
composer cs

# Fix code style automatically
composer cs-fix

# Run static analysis (PHPStan level 8)
composer phpstan

# Run PHP CS Fixer
composer cs-fixer

# Check everything
composer check

# Fix everything possible
composer fix

Quality Standards

• ✅ PSR-12 coding standard
• ✅ PHPStan level 8 (maximum strictness)
• ✅ 100% critical path test coverage
• ✅ Type declarations for all parameters and returns
• ✅ PHPDoc for complex methods
• ✅ No mixed types or dynamic properties

🏗️ Architecture

This project follows Domain-Driven Design, separating business logic from infrastructure and presentation.

Below are two new architectural diagrams that visualize core concepts.

C4 Container Architecture Diagram

The diagram below illustrates how the system is structured in terms of high-level "containers": the CLI interface, Application layer, Domain model, and Infrastructure.

Design Patterns Used

• Command Pattern - Player actions
• State Pattern - Game state management
• Repository Pattern - Data persistence
• Factory Pattern - Entity creation
• Strategy Pattern - Combat calculations
• Value Object Pattern - Immutable domain concepts

Gameplay Flow Diagram

1. Immutable Value Objects - Prevent state corruption
2. Dependency Injection - Testability and flexibility
3. Interface Segregation - Small, focused interfaces
4. Domain Events - Decoupled communication (future)
5. CQRS - Separate read/write operations (future)

Gameplay Flow Diagram

This diagram explains the game loop: reading commands, movement, combat, using items, and winning or losing.

🔄 CI/CD Pipeline

Our GitHub Actions pipeline ensures code quality:

Pipeline Stages

on: [push, pull_request]

jobs:
  syntax-check:    # Fast PHP syntax validation
  tests:           # PHPUnit tests on multiple PHP versions
  code-quality:    # PSR-12, PHPStan, CS Fixer
  security-check:  # Dependency vulnerability scan
  integration:     # Game startup and integration tests

Local CI Simulation

# Run the same checks as CI locally
composer ci

# Or manually:
composer validate --strict
composer check
composer audit

Deployment

# Create release
git flow release start 1.0.0

# Update version
nano composer.json  # Update version

# Finish release
git flow release finish 1.0.0

# Push to production
git push origin main --tags

📊 Project Status

Current Version: 0.1.0-dev

Roadmap

v1.0.0 - MVP (Due: Dec 15, 2024)

• Project setup and architecture
• Health value object
• Player entity
• Room and dungeon system
• Basic combat
• Save/Load functionality
• CLI interface

v1.1.0 - Enhancements

• Random dungeon generation
• Multiple monster types
• ASCII map display
• Colored output
• Item system

v2.0.0 - Advanced Features

• Character classes
• Skill system
• Procedural generation
• Difficulty levels
• Achievements

🐛 Troubleshooting

Common Issues

Issue: Game won't start

# Check PHP version
php -v  # Should be 8.2+

# Reinstall dependencies
rm -rf vendor composer.lock
composer install

Issue: Tests failing

# Clear test cache
rm -rf .phpunit.cache

# Run specific test with verbose output
composer test -- --verbose tests/Unit/YourTest.php

Issue: Permission denied on game save

# Fix storage permissions
chmod -R 755 storage/

📄 License

This project is licensed under the GPL-3.0 License

---

Happy Dungeon Crawling! 🗡️
_{Built with ❤️ using PHP}

```