From 80c5c0408ab51e39136abb0928fd2d0e78a9da61 Mon Sep 17 00:00:00 2001 From: dingo Date: Mon, 23 Feb 2026 04:30:56 +0000 Subject: [PATCH] Add ranked matchmaking v1 integration spec and policies --- .../context-files/scenes/ranked-play.scene.md | 65 +++++++++++++++++-- 1 file changed, 59 insertions(+), 6 deletions(-) diff --git a/Client/context-files/scenes/ranked-play.scene.md b/Client/context-files/scenes/ranked-play.scene.md index c88d4c0..ba866d2 100644 --- a/Client/context-files/scenes/ranked-play.scene.md +++ b/Client/context-files/scenes/ranked-play.scene.md @@ -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.