comunidadhll/docs/monthly-mvp-v2-scoring-design.md

Monthly MVP V2 Scoring Design

Validation Date

• 2026-03-24

Objective

Definir una formula V2 precisa, explicable e implementable para el MVP mensual usando la base V1 ya aprobada y solo las senales avanzadas V2 que hoy tienen soporte real en la repo.

Evidence Base

This proposal is based on:

• docs/monthly-mvp-ranking-scoring-design.md
• docs/monthly-player-ranking-data-audit.md
• docs/player-event-pipeline-v2-design.md
• backend/app/monthly_mvp.py
• backend/app/player_event_aggregates.py
• backend/app/historical_snapshots.py
• backend/app/payloads.py

Design Position

V2 should not replace the V1 logic with a radically different opaque model.

The correct direction is:

• keep V1 as the stable baseline
• preserve the same monthly UTC window and closed-match policy
• add a small set of advanced event-derived signals with limited weight
• avoid weapon-type or kill-type complexity until the source is richer

Meaning Of MVP In V2

V2 still means "best monthly player", not "best fragger only".

Compared with V1, V2 should reward:

• sustained offensive output
• team contribution
• efficiency over the month
• cleaner player-vs-player control in repeated encounters
• better discipline through a stricter teamkill penalty

Signals Included In V2

V2 keeps these V1 signals:

• total kills
• total support
• KPM recomputed from monthly totals
• KDA recomputed from monthly totals
• participation based on monthly time played
• monthly teamkills as penalty input

V2 adds these advanced signals:

• most_killed
• death_by
• net duel summaries

These signals are used only as modest scoring components, not as the core of the ranking.

Signals Explicitly Excluded From V2 Formula

Do not score these yet:

• weapon-type weighting
• kill-category weighting
• weapon variety bonus
• death_by_weapons
• combat, offense and defense
• win/loss context

Reason:

• the current CRCON-derived V2 layer is partial and summary-based
• weapon and type semantics are not robust enough for a serious weighted score
• adding too many low-confidence knobs would make V2 harder to defend than V1

Weapon kills remain useful for product readouts and future analysis, but not as a weighted scoring factor in this phase.

Eligibility Rules

Player eligibility for V2 should remain identical to V1:

• at least 6 closed matches in the selected month and scope
• at least 21600 seconds (6 hours) played in the selected month and scope
• non-null monthly totals for kills, deaths, support and time

Additional publication gate for the ranking itself:

• publish V2 only when the selected month and scope have matching player-event coverage for that same month_key

This avoids ranking a month with V1 totals but missing V2 event coverage.

Derived Advanced Metrics

For each eligible player-month, derive:

• most_killed_count
  • kills against the player most often killed by this player in the month
• death_by_count
  • deaths suffered from the player that killed this player most often in the month
• rivalry_edge_raw = max(0, most_killed_count - death_by_count)
• duel_control_raw
  • sum of positive net_duel_value across the player's top 3 duel pairs in the selected month and scope

Then normalize:

• rivalry_edge_score = 100 * ln(1 + rivalry_edge_raw) / ln(1 + max_rivalry_edge_raw_eligible)
• duel_control_score = 100 * ln(1 + duel_control_raw) / ln(1 + max_duel_control_raw_eligible)

Small-Sample Treatment

Advanced event signals should be damped on low-volume months.

Use:

• advanced_confidence = min(1, total_kills / 35)

Effect:

• under 35 kills, advanced components contribute only partially
• at 35+ kills, the full advanced weight is available

This keeps V2 from overreacting to tiny rivalry samples.

Normalized Core Component Scores

V2 keeps the same V1 normalization style on a 0..100 scale:

• kills_score = 100 * ln(1 + total_kills) / ln(1 + max_total_kills_eligible)
• support_score = 100 * ln(1 + total_support) / ln(1 + max_total_support_eligible)
• kpm_score = 100 * ln(1 + kpm) / ln(1 + max_kpm_eligible)
• kda_score = 100 * ln(1 + kda) / ln(1 + max_kda_eligible)
• participation_score = 100 * min(1, total_time_seconds / 28800)

V2 Teamkill Penalty

V2 should be slightly stricter than V1 on discipline.

Use:

• teamkill_penalty_v2 = min(8, total_teamkills * 0.75)

Effect:

• 1 teamkill subtracts 0.75
• 4 teamkills subtract 3
• penalty caps at 8

V2 Scoring Formula

Recommended V2 monthly MVP score:

mvp_v2_score = 0.30 * kills_score + 0.18 * support_score + 0.18 * kpm_score + 0.12 * kda_score + 0.10 * participation_score + advanced_confidence * (0.07 * rivalry_edge_score + 0.05 * duel_control_score) - teamkill_penalty_v2

Weight rationale:

• 30% kills keeps offense as the main visible driver
• 18% support preserves MVP rather than pure frag logic
• 18% KPM rewards productive time
• 12% KDA rewards cleaner performance without dominating the table
• 10% participation keeps monthly presence relevant
• 7% rivalry edge rewards players who repeatedly finish ahead in their strongest recurring encounter
• 5% duel control adds a second advanced signal but keeps it clearly bounded

Why Weapon Kills Are Not Weighted Yet

The repository can already expose kills by weapon, but the current source layer:

• is summary-based, not a full raw kill feed
• does not yet prove a stable weapon taxonomy for competitive weighting
• would invite fragile distinctions such as tank vs infantry vs artillery too early

Decision:

• do not weight kills by weapon in V2
• do not assign bonus or penalty by weapon type
• keep weapon-kill outputs as audit and UI-facing data only

Tie-Break Rules

If two players have the same mvp_v2_score, resolve ties in this order:

1. higher advanced_confidence
2. higher participation_score
3. higher kills_score
4. higher rivalry_edge_score
5. lower total_teamkills
6. alphabetical display_name
7. stable player key as final deterministic fallback

Coexistence With V1

V1 and V2 should coexist explicitly:

• V1 remains the stable default ranking
• V2 is a separate ranking version with its own ranking_version
• both versions should use the same month and scope selectors
• V2 should never overwrite or reinterpret the V1 payload contract

Implementation Guidance For Next Task

The backend task should compute V2 from:

• the same monthly player totals already used by V1
• direct player-event monthly aggregates derived from the raw ledger

Required per-player V2 outputs:

• mvp_v2_score
• advanced_confidence
• rivalry_edge_raw
• duel_control_raw
• component_scores
• teamkill_penalty_v2

Recommended ranking_version:

• v2

Final Recommendation

The correct V2 for the current repository is an incremental evolution of V1:

• keep the same explainable weighted-score structure
• add only most_killed / death_by / duel-derived pressure signals
• make discipline stricter
• refuse weapon-type weighting until the signal quality improves

This yields a V2 that is materially richer than V1 without becoming speculative.