MineSeeker/docs/game-mechanics/BONUS_POINTS_SYSTEM.md

# 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

---

## Battle Report Display Components

**IMPORTANT**: The Bonus Statistics display appears in **two places** that must be kept in sync:

### 1. Public Battle Share Page
**File**: `/templates/Game/battle_share.html.twig`
- Displays via `bshare-bonus` CSS classes
- Backend data passed from `ProfileController::battleShare()`
- Shows bonus stats as HTML table format

### 2. Profile Dialog (BattleDialog component)
**File**: `/assets/js/components/BattleDialog.jsx`
- React component using Material-UI Dialog
- Displays inside the match details modal on profile page
- Shows bonus stats using `StatRow` components in side-by-side boxes

### Synchronization Requirements

When making changes to the bonus statistics display, update **BOTH** files:

1. **Update logic/data** → Edit both template and component
2. **Change stat names** → Update both BONUS_LABELS and both display files
3. **Modify formatting** → Keep visual consistency between both displays
4. **Add new stats** → Add to both the `.twig` template AND the `.jsx` component

**Checklist for changes**:
- [ ] Update `/src/Util/TopicManager.php` if bonus calculation changes
- [ ] Update `/templates/Game/battle_share.html.twig` for public display
- [ ] Update `/assets/js/components/BattleDialog.jsx` for profile dialog
- [ ] Update `/assets/js/mine-seeker/utils/constants.jsx` if adding new stats
- [ ] Test both displays show identical data

---

## 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
- [ ] Both battle report displays tested