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

Monthly MVP Ranking Scoring Design

Validation Date

• 2026-03-24

Objective

Definir una formula V1 precisa y auditable para un ranking mensual de mejores jugadores usando solo metricas ya persistidas y suficientemente fiables en el repositorio.

Evidence Base

This proposal is based on:

• docs/monthly-player-ranking-data-audit.md
• docs/historical-domain-model.md
• docs/historical-data-quality-notes.md
• backend/app/historical_models.py
• backend/app/historical_storage.py
• backend/app/payloads.py

The design assumes the existing monthly window already used by the backend:

• UTC calendar month
• closed matches only
• fallback to the previous closed month only when the current month has no closed matches at all

V1 Meaning Of "Best Player Of The Month"

V1 should not mean "highest raw kills only" and should not pretend to measure full tactical impact that the project does not persist yet.

For this project, "monthly MVP" in V1 means:

• sustained offensive contribution across the month
• meaningful team contribution through support
• good efficiency without rewarding one or two short outlier matches
• enough participation to make the result credible

This is therefore a balanced MVP model with a light offensive bias.

Metrics Included In V1

Included metrics:

• total kills
• total support
• total time played
• KPM derived from monthly totals
• KDA derived from monthly totals
• optional teamkill penalty
• matches played as an eligibility guard

Derived metrics must be recomputed from monthly totals, not from the average of per-match ratios:

• kpm = total_kills / max(total_time_minutes, 1)
• kda = total_kills / max(total_deaths, 1)

Metrics Explicitly Out Of Scope For V1

Do not include in V1:

• combat
• offense
• defense
• matches over 100 kills
• win/loss context
• weapons profile
• kill streaks or life-span fields
• duels, most_killed, death_by
• garrisons, OPs or tactical events not confirmed as persisted

Reason:

• some are useful but would complicate the first release without improving reliability enough
• others are not persisted today or are not confirmed with stable semantics

Eligibility Rules

A player is eligible for the monthly MVP ranking only if all conditions hold:

• played at least 6 closed matches in the selected month and scope
• accumulated at least 21600 seconds (6 hours) of play time in that month
• has non-null persisted stats for kills, deaths, support and time

These gates are intentionally dual:

• match count blocks one-match outliers
• time played blocks short-session inflation

Scope Recommendation

V1 should be computed in both scopes from the same formula:

• per server
• global aggregate using all-servers

Publication recommendation:

• default visible ranking: per server
• secondary comparable view: global aggregate

Why:

• per-server ranking is easier to interpret and fairer for each community shard
• the repository already supports the logical aggregate all-servers
• using one formula for both scopes avoids redesign later

Normalized Component Scores

For each month and scope, first aggregate one row per eligible player.

Then calculate these normalized component scores 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)

Implementation notes:

• ln(1 + x) dampens extreme leaders without hiding real advantage
• participation reaches full score at 8 hours
• all max_*_eligible references are calculated inside the same month and scope

V1 Scoring Formula

Recommended V1 monthly MVP score:

mvp_score = 0.35 * kills_score + 0.20 * support_score + 0.20 * kpm_score + 0.15 * kda_score + 0.10 * participation_score - teamkill_penalty

Weight rationale:

• 35% kills: offensive impact should matter most in a first public ranking
• 20% support: keeps the model closer to MVP than to a pure frag ranking
• 20% KPM: rewards productive time, not only volume
• 15% KDA: rewards cleaner performance but keeps it below kills volume
• 10% participation: favors sustained monthly presence without turning the ranking into a pure grind chart

Teamkill Penalty

Use a small optional penalty in V1:

• teamkill_penalty = min(6, total_teamkills * 0.5)

Effect:

• 1 teamkill subtracts 0.5
• 4 teamkills subtract 2
• penalty caps at 6

This keeps the penalty visible without letting it dominate the ranking.

Tie-Break Rules

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

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

Why This V1 Is Reasonable

This design is defendable for a first release because it:

• uses only metrics already persisted with strong coverage
• recomputes efficiency from totals instead of averaging noisy per-match ratios
• blocks absurd winners from tiny samples with explicit eligibility gates
• stays interpretable enough to explain in product copy
• can be implemented from current monthly aggregates without new ingestion or schema work

V2 Expansion Path

V2 can extend the same structure without redesigning the whole ranking:

• add combat, offense and defense as extra weighted components
• add win/loss context only where team scores are present and validated
• review whether teamkill penalty should become rate-based instead of absolute
• later add tactical metrics only after deliberate persistence work

The important constraint for V2 is to preserve the same shape:

• explicit eligibility
• normalized component scores
• weighted sum
• deterministic tie-breaks