A House Divided A House DividedDocumentation
↵
Changelog
Game Design/Elections & Campaigns

Vacancy Handling

Last updated 2026-08-20

Overview#

When elected officials resign, die, or are removed from office, their seats may be filled temporarily (Senate only) or remain vacant until the next regular election cycle.

Vacancy Types by Office#

Office Vacancy Handling Duration
US Senate Governor appoints replacement Until next regular Class election
US House Seat remains vacant Until next regular House election (2 years max)
US Governor Seat remains vacant Until next regular Governor election (4 years max)
US State Senate Seat remains vacant Until next regular State Senate election (4 years max)
UK MP (Commons) Seat remains vacant Until next regular Commons election

Senate Vacancies (US Only)#

Triggering a Vacancy#

A Senate seat becomes vacant when:

Appointment Process#

When a Senate seat becomes vacant:

  1. Vacancy created: ElectedOfficial document for that senator is deleted
  2. Notification sent to Governor: "A Senate seat in your state has become vacant. You may appoint a replacement."
  3. Governor eligibility window: Governor has 48 hours (48 turns) to make an appointment
  4. If no appointment made: Seat remains vacant until next regular election

Governor Appoints Replacement#

Eligibility for appointment:

Appointment steps:

  1. Governor navigates to /officials page or receives direct link in notification
  2. Clicks "Appoint Senate Replacement" button
  3. Selects eligible character from dropdown (filtered by state and availability)
  4. Confirms appointment
  5. New ElectedOfficial document created with:
    • officeType: "senate"
    • state: [vacancy state]
    • senateClass: [Class 1/2/3] (same class as vacancy)
    • isAppointment: true
    • appointedBy: [governor characterId]
    • termStart: [now]
    • termEnd: [next Class election endTime]
  6. Notifications sent:
    • To appointee: "You have been appointed as US Senator for [State]"
    • To governor: "You have appointed [Name] as US Senator"
    • To state residents (optional future enhancement)

Appointment Duration#

Appointed senator serves until the next regular election for that Senate class.

Example:

No Special Elections for Senate#

There are no special elections for Senate vacancies. The appointed senator serves the full remainder of the term. Voters do not get to choose the replacement until the next regular Class election.

This simplifies the system and avoids mid-cycle election spam.

House Vacancies#

When a House member resigns or is removed:

Impact:

Example:

Governor Vacancies#

When a Governor resigns or is removed:

Impact:

Example:

State Senate Vacancies#

When a State Senator resigns or is removed:

Impact:

UK MP (Commons) Vacancies#

When an MP resigns or is removed:

Impact:

Note: Real-world UK holds by-elections for vacant seats. This is not implemented to avoid mid-cycle election complexity.

Resignation Mechanics#

Player Resignation#

Any player holding elected office can resign at any time (except during active election they're running in).

API: POST /api/officials/[id]/resign

Auth: Must be the character who holds that office OR an admin

Validation:

Effect:

  1. ElectedOfficial document deleted
  2. If Senate: Governor notification sent (appoint replacement)
  3. If House/Governor/State Senate/MP: No action (seat vacant)
  4. Character's currentOffice field cleared
  5. Notification sent to character: "You have resigned from [office]"

Admin Removal#

Admins can remove any official via Admin → Officials panel.

API: Same as resignation (POST /api/officials/[id]/resign with admin auth)

Effect: Identical to player resignation

Database Schema#

ElectedOfficial (Updated)#

Add fields to track appointments:

interface ElectedOfficial {
  _id: ObjectId;
  characterId: ObjectId;
  officeType: OfficeType;
  state: string;
  senateClass?: SenateClass;
  termStart: Date;
  termEnd: Date;

  // New fields for appointments
  isAppointment: boolean; // true if appointed, false if elected
  appointedBy?: ObjectId; // characterId of appointing governor (if isAppointment true)

  createdAt: Date;
  updatedAt: Date;
}

Migration#

Update all existing ElectedOfficial documents:

db.electedOfficials.updateMany(
  { isAppointment: { $exists: false } },
  { $set: { isAppointment: false } }
);

API Routes#

POST /api/officials/[id]/resign#

Resign from elected office.

Auth: Must be the character who holds that office OR admin

Body: None

Response:

{
  "success": true,
  "message": "You have resigned from US Senator for California"
}

Side effects:

POST /api/governors/appoint-senator#

Governor appoints replacement senator.

Auth: Must be an active Governor

Body:

{
  "characterId": "507f1f77bcf86cd799439011",
  "senateClass": 1
}

Validation:

Response:

{
  "success": true,
  "appointee": {
    "characterId": "507f1f77bcf86cd799439011",
    "name": "Sarah Johnson",
    "party": "democrat"
  },
  "termEnd": "2026-01-15T00:00:00Z"
}

GET /api/governors/eligible-appointees#

Get list of characters eligible for Senate appointment.

Auth: Must be an active Governor

Query params:

Response:

{
  "candidates": [
    {
      "characterId": "507f1f77bcf86cd799439011",
      "name": "Sarah Johnson",
      "party": "democrat",
      "homeState": "CA"
    }
    // ... more candidates
  ]
}

Filtering:

UI Components#

Officials Page (/officials)#

Add Vacancies section:

┌──────────────────────────────────────┐
│ 📋 Current Vacancies                  │
│                                        │
│ US Senate:                             │
│ • California, Class 1                  │
│   [Appoint Replacement] ← If governor │
│                                        │
│ US House:                              │
│ • CA-12 (vacant since June 2021)      │
│ • NY-14 (vacant since Aug 2021)       │
└──────────────────────────────────────┘

Appoint Senator Modal#

Modal triggered by "Appoint Replacement" button:

┌──────────────────────────────────────────┐
│ Appoint US Senator for California         │
│                                            │
│ Vacancy: Class 1 Senate seat              │
│ Term End: January 2026 (178 turns)        │
│                                            │
│ Select Appointee:                          │
│ [Dropdown: Sarah Johnson (Democrat)]       │
│                                            │
│ ℹ️ Note: Appointed senator serves until   │
│ the next Class 1 election in Jan 2026.    │
│                                            │
│           [Cancel]  [Confirm Appointment]  │
└──────────────────────────────────────────┘

Character Profile (If Appointed)#

Show appointment badge on appointed officials:

┌──────────────────────────────────────┐
│ Sarah Johnson                         │
│ US Senator for California (Class 1)   │
│ 📌 Appointed by Gov. Gavin Newsom     │ ← Badge
│ Term: May 2022 - Jan 2026             │
└──────────────────────────────────────┘

Resign Button#

Add to character's own profile page (when holding office):

┌──────────────────────────────────────┐
│ Your Office: US Senator for California│
│                                        │
│ ⚠️ [Resign from Office]                │
└──────────────────────────────────────┘

Clicking triggers confirmation modal:

⚠️ Are you sure you want to resign as US Senator for California?

This action cannot be undone. Your seat will become vacant immediately.

[Cancel]  [Confirm Resignation]

Future Enhancements#

  1. Special elections - Allow states to opt-in to special elections for House/State Senate
  2. Lt. Governor succession - Implement Lt. Governor office; auto-succession on Governor vacancy
  3. UK by-elections - Implement by-elections for UK MP vacancies (mirrors real-world practice)
  4. Death/mortality - Characters die of natural causes or events; triggers vacancies
  5. Expulsion - Congress can expel members via 2/3 vote; triggers vacancy

Connected pages

References →
docsElectionsdocsUnited KingdomdocsState-Level PowerwikiElection MechanicswikiUnited Kingdom
← Referenced by
None
Previous
United Kingdom