MineSeeker/docs/README.md

# Mine-Seeker Game Documentation

This directory contains comprehensive documentation about the Mine-Seeker game mechanics, testing, and implementation.

## Game Mechanics

### [Bonus Points System](./game-mechanics/BONUS_POINTS_SYSTEM.md)
Complete reference for the bonus points system including:
- All 6 bonus point types (Blind Hit, Chain Combo, Edge Mine, Endgame Mine, Safe Cell Bonus, Biggest Reveal)
- Calculation rules and examples
- Bonus statistics tracking
- Player name formatting in dialogs
- Database schema
- Implementation notes
- Testing checklist

**Recommended for**: Developers working on bonus system, AI assistants implementing or debugging bonus features, understanding game scoring mechanics.

---

## Testing

### [Testing Guide](./testing/TESTING.md)
Complete testing setup and best practices including:
- Test environment configuration
- Database isolation with DAMA Doctrine Test Bundle
- Test database setup (`mineseeker_test`)
- Writing effective tests
- Running tests (all, specific, with coverage)
- Best practices (AAA pattern, factories, type hints)
- CI/CD integration examples
- Troubleshooting guide

**Recommended for**: All developers, understanding test infrastructure, writing new tests, debugging test failures.

### [Factory Documentation](./testing/FACTORIES.md)
Detailed API reference for Zenstruck Foundry factories:
- All available factories (User, Gamer, PlayedGame, Step, Grid, etc.)
- Factory usage examples
- Creating related entities
- Repository access
- Database isolation explanation
- Best practices and patterns

**Recommended for**: Writing tests with test data, understanding factory patterns, creating complex test scenarios.

---

## Technical Documentation

### [Fonts](./FONTS.md)
TrueType fonts used for server-side image generation:
- Font file locations
- Usage in battle card generation
- Web vs. server-side font formats

**Recommended for**: Working on OG image generation, understanding font rendering.

---

## Quick Reference

### Bonus Points at a Glance
| Bonus Type | Points | Condition |
|-----------|--------|-----------|
| Blind Hit | +2 | Mine with no revealed numbered neighbors |
| Edge Mine | +1 | Mine on board boundary (row/col 0 or 15) |
| Endgame Mine | +3 | Mine clicked when ≤10 mines remain |
| Safe Cell | +0.5 each | ≥2 safe cells revealed (min requirement) |
| Chain Combo | Tracked | Consecutive mine clicks (no safe clicks) |
| Biggest Reveal | Tracked | Largest number of safe cells revealed |

### Available Test Factories
| Factory | Entity | Purpose |
|---------|--------|---------|
| `UserFactory` | `User` | Registered users |
| `GamerFactory` | `Gamer` | Anonymous/guest players |
| `PlayedGameFactory` | `PlayedGame` | Game records |
| `StepFactory` | `Step` | Game moves |
| `GridFactory` | `Grid` | Game grids (16×16) |
| `GridRowFactory` | `GridRow` | Grid rows |
| `WebAuthnCredentialFactory` | `WebAuthnCredential` | Passkey credentials |
| `ContactMessageFactory` | `ContactMessage` | Contact messages |

### Running Tests
```bash
# Recommended: Use Makefile
make test-db-setup

# Or manually:
# All tests
vendor/bin/phpunit

# Specific file
vendor/bin/phpunit tests/Controller/ProfileControllerTest.php

# Specific method
vendor/bin/phpunit --filter testProfilePageRequiresAuthentication

# With coverage (requires Xdebug/PCOV)
XDEBUG_MODE=coverage vendor/bin/phpunit --coverage-html coverage/

# With increased memory
php -d memory_limit=512M vendor/bin/phpunit
```

---

## Files Using This Information

### Game Mechanics
- Backend: `/src/Util/TopicManager.php`
- Frontend: `/assets/js/mine-seeker/contexts/GameProvider.jsx`
- UI: `/assets/js/mine-seeker/components/BonusStatsDialog.jsx`
- Constants: `/assets/js/mine-seeker/utils/constants.jsx`

### Testing
- Test Base Class: `/tests/WebTestCase.php`
- Factories: `/tests/Factory/`
- Example Tests: `/tests/Integration/FactoryExampleTest.php`
- PHPUnit Config: `/phpunit.dist.xml`
- Bundle Config: `/config/bundles.php`

---

## Additional Resources

- **[Main README](../README.md)** - Project overview, installation, deployment
- **[AI Agent Guidelines](../AGENTS.md)** - Comprehensive guide for AI coding agents
- **[Zenstruck Foundry](https://symfony.com/bundles/ZenstruckFoundryBundle/current/index.html)** - Official Foundry documentation
- **[PHPUnit](https://phpunit.de/)** - PHPUnit documentation
- **[Symfony Testing](https://symfony.com/doc/current/testing.html)** - Symfony testing guide