comunidadhll/docs/elo-mmr-monthly-ranking-design.md

Elo/MMR Monthly Ranking Design

Scope

This repository now exposes a first operational Elo/MMR-like system inspired by sistema_elo_mensual_hll.pdf, but constrained to signals that are really available today.

The implementation keeps the same conceptual split:

• persistent MMR
• monthly MonthlyRankScore

It does not claim full parity with the PDF. Every major signal is labeled as:

• exact
• approximate
• not_available

Real Inputs Available Today

Exact today from persisted historical CRCON/public-scoreboard data:

• closed match identity
• server scope
• player identity
• team side
• kills
• deaths
• support
• teamkills
• combat score
• offense score
• defense score
• match timestamps when present
• final allied/axis score

Exact today from current product state but not required by the core engine:

• player-event V2 summaries for duels, most-killed, death-by and weapon summaries

Approximate only:

• role_bucket
  • inferred from the dominant scoreboard axis among combat, offense, defense and support
• ObjectiveIndex
  • proxied with offense + defense because there is no tactical event feed
• StrengthOfSchedule
  • proxied with match quality and lobby density because there is no opponent MMR model yet

Not available today:

• explicit squad role / commander / SL role
• garrisons and OPs destroyed
• revives
• AFK and leave events
• precise leadership telemetry
• exact tactical objective event stream
• exact opponent-strength graph by roster

Current Capability Contract

Match validity

Current rule:

• match must be closed
• match duration must be at least 15 minutes
• match must have at least 20 persisted player rows

Duration source:

• exact if started_at and ended_at exist
• approximate if we must fall back to max player time_seconds

Quality factor Q

Current Q is a bounded mix of:

• player density
• match duration
• score completeness

This is an operational approximation of the PDF quality factor and is labelled:

• exact for the density and score-completeness inputs
• exact or approximate for duration depending on timestamp availability

Buckets

Implemented:

• duration bucket
• mode retention through game_mode
• approximate role_bucket

Not implemented yet:

• literal class role bucket

Subindices

Implemented now:

• OutcomeScore: exact
• CombatIndex: exact
• ObjectiveIndex: approximate
• UtilityIndex: exact
• LeadershipIndex: not_available
• DisciplineIndex: exact for teamkills only

ImpactScore

Implemented with role-inspired weights, but the role itself is approximate, so the final ImpactScore is operationally approximate.

DeltaMMR

Implemented from:

• OutcomeScore
• ImpactScore
• quality factor Q

The resulting DeltaMMR is real and persisted, but inherits the mixed availability of the inputs above.

Storage Model

Tables added in backend SQLite:

• elo_mmr_player_ratings
• elo_mmr_match_results
• elo_mmr_monthly_rankings
• elo_mmr_monthly_checkpoints

Meaning:

• elo_mmr_player_ratings
  • current persistent rating per player and scope
• elo_mmr_match_results
  • per-match scoring trace used to explain rating movement
• elo_mmr_monthly_rankings
  • monthly ranking rows ready for product/API
• elo_mmr_monthly_checkpoints
  • generated-at metadata plus source policy and capability summary

Scopes persisted:

• per historical server
• all-servers

Runtime Source Policy

The Elo/MMR engine follows the same historical policy as the rest of backend:

• primary intent: rcon
• current competitive calculation fallback: public-scoreboard

Why fallback still exists here:

• the current RCON historical read model only supports coverage and recent activity
• it does not yet expose enough competitive match detail to support this Elo/MMR engine directly

That fallback is exposed in API metadata through:

• primary_source
• selected_source
• fallback_used
• fallback_reason
• source_attempts

Product Read Model

Current API surfaces:

• /api/historical/elo-mmr/leaderboard
• /api/historical/elo-mmr/player

These payloads expose:

• persistent rating
• monthly ranking score
• eligibility
• component breakdown
• exact/approximate/partial capability metadata

Important Limitations

This first version should be treated as:

• operational
• honest about accuracy
• compatible with future expansion

It should not be described as:

• a perfect Elo system
• full parity with the PDF
• a complete tactical rating model

Planned Expansion Path

The current design is compatible with future upgrades once real telemetry exists:

• replace approximate ObjectiveIndex with event-driven tactical signals
• add LeadershipIndex when squad/command telemetry exists
• replace approximate StrengthOfSchedule with opponent MMR graph logic
• feed V2 duels and weapon signals into richer combat weighting when their coverage is sufficient