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

{
  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