Mine-Seeker Game Documentation
This directory contains comprehensive documentation about the Mine-Seeker game mechanics, testing, and deployment.
Game Mechanics
Bonus Points System
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
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
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
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
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
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
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
# 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
# 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 - Project overview, installation, deployment
- AI Agent Guidelines - Comprehensive guide for AI coding agents
- Zenstruck Foundry - Official Foundry documentation
- PHPUnit - PHPUnit documentation
- Symfony Testing - Symfony testing guide
- Gitea Actions - Gitea Actions documentation
- Docker Compose - Docker Compose reference