Add ranked matchmaking v1 integration spec and policies

This commit is contained in:
dingo
2026-02-23 04:30:56 +00:00
parent d6a0b393d5
commit 80c5c0408a
@@ -69,9 +69,62 @@
5. If accepted (or auto-accept policy), allocate match server and transition to gameplay.
6. If declined/timeout/disconnect, apply policy (requeue/penalty) and notify client.
### Open Policy Decisions
1. Accept flow: explicit accept button vs auto-accept on match found.
2. Timeout behavior and dodge penalties.
3. How aggressive search-window expansion should be by queue time.
4. Party/duo rules (if any) for ranked.
5. Placement match handling for new season/new player.
## Matchmaking v1 Integration Spec
### v1 Decisions (Locked)
1. **Accept flow:** auto-accept (no ready-check popup) for fastest queue-to-match path.
2. **Queue type:** solo queue only in v1.
3. **Deck/ArchSpirit lock:** locked at queue join; changing either requires leaving queue.
4. **Placement:** first 10 ranked matches per season are placement-calibrated.
### v1 Search Window Expansion
- `0s-30s`: ±75 MMR, same rank tier bucket, same region preferred.
- `31s-60s`: ±125 MMR, adjacent rank tier allowed, same region strongly preferred.
- `61s-120s`: ±200 MMR, broader rank band, nearby low-latency regions allowed.
- `121s+`: ±300 MMR, widest v1 bounds, any allowed region under latency cap.
### Region/Latency Policy
- Preferred region from player profile/ping map.
- Hard reject match candidates where predicted latency exceeds v1 cap (e.g. 140ms).
- If no candidate under cap after 180s, notify client with option to keep waiting or cancel.
### Anti-Rematch / Pairing Controls
- Avoid same-opponent rematch within last 2 completed ranked games when alternatives exist.
- Soft rule only (can be bypassed at high queue times to avoid deadlocks).
### Dodge / Disconnect Policy (v1)
- Since v1 is auto-accept, “dodge” is treated as disconnect/failure to load match.
- First offense in rolling 24h: warning + immediate requeue allowed.
- Repeated offenses: escalating queue lockouts (e.g. 2m, 5m, 15m).
- Server records offense events for moderation review.
### v1 Client Integration States
- `Idle`
- `ValidatingLoadout`
- `QueueJoining`
- `InQueue`
- `MatchAllocated`
- `TransitionToGameplay`
- `QueueError`
### v1 Server Event Contract Additions
#### Server -> Client (`RankedQueueStatus`)
- `requestId`
- `queueTicketId`
- `elapsedSeconds`
- `searchWindowTier` (`T1`/`T2`/`T3`/`T4`)
- `estimatedWaitSeconds`
- `status` (`searching` | `allocating` | `requeue_required`)
#### Server -> Client (`RankedQueuePenalty`)
- `requestId`
- `penaltyType` (`warning` | `lockout`)
- `lockoutSeconds` (optional)
- `reasonCode`
### Telemetry / Audit Hooks (v1)
- Queue enter/leave events with `queueTicketId`, `deckId`, `archspiritId`.
- Match candidate evaluations (anonymized opponent id, accept/reject reason).
- Final match allocation event with `matchId`, region, latency estimate.
- Disconnect/penalty events with escalation tier.