new: usr: add initialization bonus points' system to the gameplay #5

2026-04-18 12:57:20 +02:00
parent 0cc9cdaf07
commit 25f2aaab8c
15 changed files with 946 additions and 52 deletions
--- a/docs/README.md
+++ b/docs/README.md
@@ -0,0 +1,47 @@
+# Mine-Seeker Game Documentation
+
+This directory contains comprehensive documentation about the Mine-Seeker game mechanics 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.
+
+---
+
+## 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 |
+
+### Key Rules
+- Safe cell bonus only awarded for ≥2 cells minimum
+- Chain counter resets on any safe cell click
+- Endgame threshold: 51 - (redPoints + bluePoints) ≤ 10
+- Bonus stats are per-player and persist in database
+
+---
+
+## Files Using This Information
+- 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`
+
+
--- a/docs/game-mechanics/BONUS_POINTS_SYSTEM.md
+++ b/docs/game-mechanics/BONUS_POINTS_SYSTEM.md
@@ -0,0 +1,133 @@
+# Mine-Seeker Bonus Points System
+
+## Overview
+The Mine-Seeker game includes a bonus points system that rewards skilled play. Bonus points are tracked separately from the main score and displayed in the "Bonus Statistics" dialog.
+
+## Bonus Point Types
+
+### 1. Blind Hit (+2 points)
+**When**: Click a mine with no revealed numbered neighbors around it.
+
+**Example**: Mine surrounded by unrevealed cells = +2 points
+
+---
+
+### 2. Chain Combo
+**When**: Click consecutive mines without clicking any safe cell in between.
+
+**Tracked as**:
+- `chainCurrent`: Current streak (resets when you click a safe cell)
+- `chainBest`: Longest streak achieved
+
+**Example**: Mine → Mine → Mine = chainBest becomes 3
+
+---
+
+### 3. Edge Mine (+1 point)
+**When**: Click a mine on the board boundary (row 0, row 15, col 0, or col 15).
+
+**Example**: Click a mine on the edge = +1 point
+
+---
+
+### 4. Endgame Mine (+3 points)
+**When**: Click a mine when 10 or fewer mines remain on the board.
+
+**Calculation**: `51 total mines - (red_points + blue_points) = mines_remaining`
+
+**Example**: When 8 mines remain, click one = +3 points
+
+---
+
+### 5. Safe Cell Bonus (+0.5 points per cell)
+**When**: Click a safe cell and reveal 2 or more cells.
+
+**Important**: Minimum 2 cells required. Single cell reveals = 0 points.
+
+**Examples**:
+- Reveal 1 safe cell = 0 points
+- Reveal 2 safe cells = 1.0 points
+- Reveal 11 safe cells = 5.5 points
+
+---
+
+### 6. Biggest Reveal (Tracking stat)
+**What**: Tracks the largest number of safe cells revealed in one click.
+
+**Example**: Largest reveal in a game = 15 cells shown in stats
+
+---
+
+## Bonus Statistics Display
+
+### Dialog Shows
+- Both players' bonus statistics side-by-side
+- Each stat with label, description, and value
+- Total bonus points per player
+
+### Player Name Rules
+- `anon_*` usernames → displays as "Anonymous"
+- Names longer than 10 chars → truncated to 7 chars + "..." (example: `VeryLongName` → `VeryLon...`)
+
+---
+
+## Tracked Statistics
+
+```javascript
+{
+  blindHits: 0,      // Blind hit mines clicked
+  chainBest: 0,      // Longest mine streak
+  chainCurrent: 0,   // Current active streak
+  lastMineHits: 0,   // Endgame mines clicked
+  edgeMines: 0,      // Edge mine clicks
+  biggestReveal: 0   // Largest safe cell reveal
+}
+```
+
+---
+
+## Database
+- `red_bonus_points` (FLOAT) — Red player's total bonus points
+- `blue_bonus_points` (FLOAT) — Blue player's total bonus points
+- `red_bonus_stats` (JSON) — Red player's tracked stats
+- `blue_bonus_stats` (JSON) — Blue player's tracked stats
+
+---
+
+## 📋 Documentation Maintenance
+
+**IMPORTANT**: This documentation must be updated whenever:
+- New bonus types are added
+- Point values change
+- Bonus calculation logic changes
+- New stats are tracked
+- Bonus display rules change
+
+**Update these files**:
+1. This file (`BONUS_POINTS_SYSTEM.md`) — Update descriptions and examples
+2. Code comments in `/src/Util/TopicManager.php` — Explain calculation logic
+3. `/docs/README.md` — Update Quick Reference table if values change
+
+**Keep documentation**:
+- ✅ Simple and clear
+- ✅ With real code examples
+- ✅ Synchronized with actual code behavior
+- ✅ Updated before/after feature changes
+
+---
+
+## Implementation Files
+- Backend: `/src/Util/TopicManager.php` — Bonus calculation logic
+- Frontend: `/assets/js/mine-seeker/contexts/GameProvider.jsx` — State sync
+- UI: `/assets/js/mine-seeker/components/BonusStatsDialog.jsx` — Display dialog
+- Constants: `/assets/js/mine-seeker/utils/constants.jsx` — Labels and defaults
+
+---
+
+## Quick Checklist for Changes
+- [ ] Code changes implemented
+- [ ] This documentation updated
+- [ ] `/docs/README.md` Quick Reference table updated
+- [ ] Code comments added/updated
+- [ ] Examples updated to match new behavior
+