# Voting Systems

## Purpose
This document describes map-vote and RTV runtime behavior, ownership, and integration points.

## Authority map
- Map vote runtime: `Code/Game/Voting/MapVoteSystem.cs`
  - Owns vote option generation, vote collection, winner selection, and map change dispatch.
- RTV runtime: `Code/Game/Voting/RTVSystem.cs`
  - Owns yes/no vote flow for map change or kick requests.
- Round-end trigger: `Code/Game/Maps/StartMapVoteOnEnd.cs`
  - Starts map vote from game-end flow.
- UI overlays:
  - `Code/UI/Features/Voting/MapVote/MapVoteOverlay.razor`
  - `Code/UI/Features/Voting/MapVote/MapVoteCard.razor`
  - `Code/UI/Features/Voting/RTV/RTVOverlay.razor`
- Main menu preload hook:
  - `Code/UI/Features/Menus/MainMenu/NewMainMenuRoot.razor` preloads whitelist packages.

## Map vote flow
1. Host creates `MapVoteSystem`.
2. Vote options are populated (curated/uncurated or current-map mode).
3. Clients submit votes via host RPC.
4. Host resolves winner (including no-vote/draw handling).
5. Host changes level immediately or defers change to round-end in RTV mode.

## RTV flow
1. Host creates `RTVSystem` with vote type and prompt text.
2. Clients vote yes/no via host RPC.
3. If threshold passes:
  - map change during a live round -> marks map vote pending for the current round end and lets the normal game-end pipeline open the map vote,
  - map change in `WaitingForPlayers` with multiple eligible voters -> keeps the map vote pending until the next round ends,
  - map change in `WaitingForPlayers` with only one eligible voter, or after the game has already ended -> starts map vote immediately,
  - kick -> routes to network kick command.
4. The player who starts an RTV is automatically counted as a yes vote.

## Operational notes
- Host authority only for vote creation/resolution.
- Map package whitelist uses an async cache to avoid repeated fetch delay.
- Uncurated package discovery merges discoverable `type:map` and scene-asset packages, then adds any explicit blacklist idents as uncurated seeds.
- Vote option count is host-configurable through lobby start settings and `MapVoteConfig` (default 8, clamped 3-12).
- UI panel can be minimized/restored; core vote state remains host authoritative.

## Related docs
- Host game loop: `Code/Core/Documentation/Structure/game-loop.md`
- UI architecture: `Code/Core/Documentation/ui-architecture.md`