134 lines
3.7 KiB
Markdown
134 lines
3.7 KiB
Markdown
|
# 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
|
||
|
|
|