SplendidBear-Websites/MineSeeker
Private
Public Access
1
0
Fork 0
Code Pull Requests 1 Releases Activity
Files
199bb7e5259c3ccb2be985eb4b140739c80635a5
MineSeeker/docs/README.md

6.3 KiB
Raw Blame History

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

View Git Blame Copy Permalink