196 lines
6.3 KiB
Markdown
196 lines
6.3 KiB
Markdown
# Mine-Seeker Game Documentation
|
||
|
||
This directory contains comprehensive documentation about the Mine-Seeker game mechanics, testing, and deployment.
|
||
|
||
## 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`)
|
||
- Modern PHPUnit attributes (`#[Test]`, `#[TestDox]`)
|
||
- 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.
|
||
|
||
### [Quick Reference](./testing/QUICK_REFERENCE.md)
|
||
Quick command reference for testing:
|
||
- Common test commands
|
||
- Factory usage cheat sheet
|
||
- Troubleshooting tips
|
||
|
||
**Recommended for**: Quick lookups during development.
|
||
|
||
---
|
||
|
||
## CI/CD & Deployment
|
||
|
||
### [CI/CD Integration Guide](./CI_CD.md)
|
||
Comprehensive guide for continuous integration and deployment:
|
||
- Gitea Actions workflows (CI and CD pipelines)
|
||
- Automated testing on every push/PR
|
||
- Deployment process with pre-deployment testing
|
||
- Configuration requirements (secrets, variables)
|
||
- Rollback procedures
|
||
- Security considerations
|
||
- Performance optimization
|
||
- Monitoring and notifications
|
||
- Troubleshooting deployment issues
|
||
|
||
**Recommended for**: Understanding deployment pipeline, setting up CI/CD, debugging deployment failures, production operations.
|
||
|
||
### [CI/CD Quick Reference](./testing/CI_CD_QUICK_REFERENCE.md)
|
||
Quick reference for CI/CD operations:
|
||
- Common commands (testing, deployment, rollback)
|
||
- Workflow diagrams (CI and CD pipelines)
|
||
- Status badges for README
|
||
- Common issues and solutions
|
||
- Environment variables
|
||
- Monitoring links
|
||
|
||
**Recommended for**: Quick deployments, troubleshooting, day-to-day operations.
|
||
|
||
---
|
||
|
||
## 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
|
||
|
||
### Test Suite Overview
|
||
| Metric | Value |
|
||
|--------|-------|
|
||
| Total Tests | 71 |
|
||
| Total Assertions | 227 |
|
||
| Execution Time | ~6-8 seconds |
|
||
| Coverage | Controller, DTO, Entity, Service, Integration |
|
||
|
||
### 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
|
||
# Setup (first time only)
|
||
make test-db-setup
|
||
|
||
# Run all tests
|
||
make test
|
||
|
||
# Run with documentation output
|
||
vendor/bin/phpunit --testdox
|
||
|
||
# Specific file
|
||
vendor/bin/phpunit tests/Controller/ProfileControllerTest.php
|
||
|
||
# With coverage (requires Xdebug/PCOV)
|
||
XDEBUG_MODE=coverage vendor/bin/phpunit --coverage-html var/coverage
|
||
```
|
||
|
||
### CI/CD Commands
|
||
```bash
|
||
# Deploy to production
|
||
git tag -a v1.2.3 -m "Release version 1.2.3"
|
||
git push origin v1.2.3
|
||
|
||
# View CI/CD runs
|
||
# https://source.splendidbear.org/SplendidBear-Websites/Mine/actions
|
||
|
||
# Rollback deployment
|
||
git push origin v1.2.2 # Deploy previous version
|
||
```
|
||
|
||
---
|
||
|
||
## 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`
|
||
|
||
### CI/CD
|
||
- CI Workflow: `/.gitea/workflows/ci.yml`
|
||
- CD Workflow: `/.gitea/workflows/deploy.yml`
|
||
- Dockerfile: `/Dockerfile`
|
||
- Docker Compose: `/compose.yaml`
|
||
|
||
---
|
||
|
||
## 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
|
||
- **[Gitea Actions](https://docs.gitea.com/usage/actions/overview)** - Gitea Actions documentation
|
||
- **[Docker Compose](https://docs.docker.com/compose/)** - Docker Compose reference
|