# Kingpin Mode — Game Design Document

# Kingpin Mode — Game Design Document

**Platform:** FiveM (GTA V multiplayer)
**Genre:** Persistent faction PvP / crime RP-lite
**Status:** Design draft v2 (restructured)

---

## 1. Vision

Kingpin Mode is a faction-versus-faction game mode where every player is either building a criminal empire or trying to tear one down. Criminals climb toward becoming the **Kingpin**; Authorities climb toward becoming the **Mayor**. The two ladders are opposed: every criminal success weakens the city, every Authority success weakens the underworld, and both leaders can be toppled.

The mode ships as a modular resource pack so server owners can enable only the systems they want.

### Design pillars

1. **Symmetric agency.** Both factions have things to do at all times, not just when the other side acts. If a mechanic exists for Criminals, there is an equivalent stake for Authorities.
2. **Power is temporary.** Kingpin and Mayor are positions, not trophies. They are won, defended, and lost through gameplay.
3. **Money must leave the economy.** Every income source has a matching sink so currency keeps meaning something.
4. **Fun at 8 players.** All core loops must work on a quiet weeknight. Large-population features are layered on top, never required.
5. **Modular, not fragmented.** Core modules deliver a complete game. Optional modules extend it; none are prerequisites for fun.

---

## 2. Core Loop

```
Take a job or mission
    → earn money / reputation / faction influence
        → spend on upgrades, businesses, territory, or faction resources
            → climb the rank ladder
                → contest leadership (Kingpin / Mayor)
                    → hold power under pressure until deposed or the season ends
```

The two factions run this loop in parallel, and each faction's actions create the *content* for the other: a criminal drug lab is an Authority raid target; an Authority patrol route is a criminal ambush opportunity.

---

## 3. Sessions and Seasons

Kingpin Mode is **persistent within a season**. A season is a configurable window (default: 30 days). At season end:

- Kingpin and Mayor are recorded in a hall of fame.
- Territories, businesses, and faction treasuries reset.
- Player *rank* persists at a reduced level (default: drop two tiers) so veterans keep an edge without locking out newcomers.
- Cosmetic and title unlocks persist permanently.

**Why:** persistent faction servers die when an entrenched hierarchy leaves new players with no path up. Seasons keep the ladder climbable and give leadership a natural expiry even if nobody deposes them.

Server owners can disable seasons entirely for a pure-persistence experience.

---

## 4. Factions

### 4.1 Criminals

**Fantasy:** rise from street hustler to the untouchable head of the underworld.

**Always-available activities (solo or small group):**
- Street jobs: pickpocketing, car theft, drug corner sales, smuggling runs.
- Business management: run and defend drug labs, chop shops, smuggling fronts, underground casinos.
- Territory pressure: tag rival turf, collect protection from businesses in owned districts.

**Group activities:**
- Multi-stage heists (see §6).
- Gang wars over territory (see §9).

**Faction resources:** Criminal factions maintain a shared **war chest** funded by a cut of member earnings (rate set by the Kingpin). It pays for heist equipment, bribes, and territory defense.

### 4.2 Authorities

**Fantasy:** rise from patrol officer to the Mayor who runs the city.

**Always-available activities (solo or small group):**
The Authority side must have a proactive loop that does not depend on criminals doing something first.

- **Patrol & dispatch:** owned districts generate procedural incidents (disturbances, traffic stops, NPC crime) that reward response time and reduce district *heat*.
- **Investigation chains:** evidence left by criminal activity (heists, business operations, territory tags) spawns leads. Following a chain — interview, forensics, surveillance — produces a **warrant**, which unlocks a raid (see §6).
- **Municipal management:** Authorities collectively hold the **city budget**, funded by taxes on legal income and seized criminal assets. The Mayor sets tax rate and allocates budget to equipment tiers, patrol coverage, and district infrastructure.

**Group activities:**
- Multi-stage raids against warranted criminal targets.
- Heist interdiction: responding to a live heist alert.
- District lockdowns to reclaim contested territory.

**Faction resources:** the **city budget** (see above). Authority "businesses" from v1 are replaced by municipal control — the interesting verb is *governing*, not running a construction firm.

### 4.3 Faction parity table

| Criminal | Authority |
|---|---|
| War chest | City budget |
| Heist | Raid |
| Businesses (illegal) | Districts (municipal) |
| Gang war | Lockdown |
| Kingpin | Mayor |
| Reputation | Commendations |
| Mole (Authority agent in gang) | Dirty Cop (Criminal agent in police) |
| Loyalty test | Internal Affairs |

---

## 5. Leadership: Kingpin and Mayor

Leadership is the endgame and the most important system to get right. Both positions must be **earned, exercised, and losable**.

### 5.1 Becoming Kingpin

- Reach the top criminal rank.
- Hold a minimum share of territory (default: 30%) or war chest contribution.
- **Challenge** the sitting Kingpin: a declared gang war with a time limit. The challenger wins by seizing the Kingpin's home territory or by the Kingpin's faction failing a defense objective.
- If no Kingpin exists, the first eligible player to hold the territory threshold for 48 hours claims the title.

### 5.2 Becoming Mayor

- Reach the top Authority rank.
- **Election:** every 7 in-season days (configurable), eligible top-rank players may run. All Authority players vote. Votes are weighted by commendations earned that week, so active players matter more than alt accounts.
- Between elections, the sitting Mayor can be **recalled** if the city's overall heat exceeds a threshold for 24 hours — the criminals are winning, and the faction needs new leadership.

### 5.3 Powers

| Kingpin | Mayor |
|---|---|
| Set war chest cut rate | Set tax rate |
| Approve/deny heist plans | Approve/deny raid warrants |
| Assign territory to lieutenants | Assign districts to precinct captains |
| Spend war chest on faction upgrades | Spend budget on faction upgrades |
| Declare gang war | Declare lockdown |
| Place bounties | Place most-wanted flags |

Leaders **cannot** demote other players or block their progression. Rank is XP-based (see §7); leadership grants authority over *faction resources*, not over other players' accounts. This prevents the position from becoming a griefing tool.

### 5.4 Losing leadership

- Kingpin: lose a challenge, be arrested (see §10), or go inactive for 72 hours.
- Mayor: lose an election, be recalled, or go inactive for 72 hours.
- Both: season end.

---

## 5A. Infiltrators

Each faction can plant agents inside the other. A **Dirty Cop** is a Criminal-aligned player operating inside the Authority faction; a **Mole** (or "good guy criminal") is an Authority-aligned player operating inside a criminal gang. Infiltrators are the mode's hidden-role layer and the main reason planning stages (§6) are not perfectly secret.

### Becoming an infiltrator

- Unlocked at Tier 3. The player's *true* faction remains their original one; they are given a cover identity in the other faction, starting at Tier 1 there.
- Slots are limited: default one infiltrator per 6 online members of the **host** faction, so a small faction can't be hollowed out.
- The Kingpin/Mayor (or a delegated Tier 5) approves each infiltrator. Leadership knows who their own agents are; nobody else does.
- An infiltrator earns XP in **both** ladders while under cover, but their cover rank caps at Tier 4 — infiltrators can never become Kingpin or Mayor of the faction they are infiltrating.

### What infiltrators can do

| Dirty Cop (in Authority) | Mole (in gang) |
|---|---|
| Leak warrant targets and raid timing to the gang before breach | Leak heist targets and timing to Authorities before execution |
| Delay dispatch response; "lose" evidence to break an investigation chain | Sabotage prep (faulty getaway car, wrong drill) so the heist fails |
| Sell seized contraband back out of the evidence locker | Feed the investigation chain directly, skipping steps toward a warrant |
| Tip off a business owner that heat is rising | Wear a wire during planning so the raid team gets a full roster |

Every infiltrator action has a **cover risk**. Each action rolls against the player's cover integrity; failed rolls generate suspicion visible to the host faction's counter-intelligence tools.

### Detection and exposure

- **Internal Affairs (Authority)** and **Loyalty Tests (Criminal)** are Tier 4+ activities that investigate suspicion. They cost faction resources (budget or war chest) and take time, so accusing everyone is expensive.
- A **loyalty test** is a small mission the suspect must complete alone; a Mole faces a real choice about whether to do something that hurts their true faction.
- Exposure is a **faction decision**, not automatic: the investigator presents evidence and the leader confirms. Wrongful exposure of a loyal member costs the accuser commendations/reputation and refunds the accused.

### Consequences when exposed

- Cover identity is burned: the player is ejected from the host faction and flagged for a cooldown (default 7 in-season days) before they can infiltrate again.
- An exposed Dirty Cop is treated as a criminal by Authorities: immediate warrant, seizure of any Authority equipment. An exposed Mole has a bounty placed automatically by the gang.
- The host faction gains a **counter-intel** bonus: the infiltrator's true faction has its next mission planning stage exposed.

### Why this works with the rest of the design

- It gives Tier 3–4 players — the mid-game dead zone in most faction modes — a distinct, high-tension role.
- It turns §6's "sloppy prep leaves evidence" into a social system: was the leak an accident or a person?
- It creates a legitimate reason for leaders to *not* approve every heist or raid, which makes the leadership powers in §5.3 meaningful.

### Guardrails

- Infiltrators cannot directly steal from personal accounts or the war chest/budget — only leak, sabotage, and misdirect. This keeps the role about information, not grief.
- Server owners can disable the system entirely or cap slots to zero for a faction.

---

## 6. Multi-Stage Missions

Heists and raids are the flagship group content and the primary point of contact between factions. They are designed as mirrors.

### 6.1 Heists (Criminal)

| Stage | Description | Authority visibility |
|---|---|---|
| **Plan** | Leader selects target (bank, armored truck, jewelry store, rival business). Kingpin approves. Team of 2–6 assembles. | None |
| **Prep** | Acquire equipment (drills, getaway vehicle, disguises) via jobs or war chest. Each prep step leaves optional **evidence** if done sloppily. | Evidence may spawn investigation leads |
| **Execute** | Timed on-site objectives. Alarm triggers on failure conditions. | Alarm broadcasts a live heist alert with location |
| **Escape** | Reach a safehouse within a time limit while evading pursuit. Loot is banked only on arrival. | Full pursuit; roadblocks and spike strips available |

Payout scales with target difficulty and is split by the leader. Failure costs prep equipment and may result in arrest.

### 6.2 Raids (Authority)

| Stage | Description | Criminal visibility |
|---|---|---|
| **Investigate** | Follow evidence chain to identify a target business or hideout. Produces a warrant request. | Criminal owner sees rising "heat" on the business |
| **Warrant** | Mayor (or delegated captain) approves. Team of 2–6 assembles. | None |
| **Breach** | Timed entry. Criminals present are alerted on breach and can fight or flee. | Live raid alert to business owner and faction |
| **Secure** | Arrest suspects, seize contraband and cash. Seized assets go to city budget. | — |

Success shuts the business down for a cooldown and removes its territory income. Failure (all officers down or timer expiry) refunds nothing and lowers district morale.

### 6.3 Interaction rules

- A heist in progress can be interdicted by any Authority player who responds to the alert. Interdiction success counts as a raid-tier reward.
- A raid in progress can be defended by any Criminal in the faction. Repelling it grants a heist-tier reward.
- Neither faction can *see* the other's planning stages, but sloppy prep generates evidence. This makes stealth a real choice rather than a flavor text.

---

## 7. Progression and Ranks

Rank is earned through **XP**, awarded for completing jobs, missions, and faction objectives. XP is never awarded or removed by other players.

Default ladders (fully customizable via the Faction Hierarchy Module):

| Tier | Criminal | Authority |
|---|---|---|
| 1 | Runner | Cadet |
| 2 | Hustler | Officer |
| 3 | Enforcer | Detective |
| 4 | Lieutenant | Sergeant |
| 5 | Underboss | Captain |
| 6 | **Kingpin** (contested) | **Mayor** (elected) |

Each tier unlocks job types, equipment tiers, and mission roles. Tier 5 is the leadership-eligible tier.

---

## 8. Economy

### 8.1 Income sources

| Source | Criminal | Authority |
|---|---|---|
| Jobs | Street crime payouts | Patrol/incident rewards |
| Missions | Heist loot | Raid seizures (to budget) + commendation bonus |
| Passive | Business output, territory protection | District tax revenue (to budget) + salary |
| Faction | War chest disbursements | Budget salary tiers set by Mayor |

### 8.2 Sinks (mandatory for balance)

| Sink | Criminal | Authority |
|---|---|---|
| Upkeep | Business supply costs; territory defense | Equipment maintenance; patrol fuel |
| Loss | Equipment lost on arrest; contraband seized | Equipment lost on death |
| Consequence | Bail, bribes | Fines for misconduct (wrongful arrest, civilian damage) |
| Faction tax | War chest cut | Income tax (rate set by Mayor) |
| Upgrades | Weapons, vehicles, business tiers | Weapons, vehicles, district infrastructure |

Design target: a mid-tier player should burn roughly 60–70% of gross income on sinks. Tune upward if hoarding appears.

### 8.3 Player trading

Contraband, equipment, and vehicles are tradeable items with durability. The Black Market (optional module) is the criminal exchange; Authorities trade through an evidence-locker auction of seized goods.

---

## 9. Territory

The map is divided into districts. Every district is always controlled by *someone*: a criminal gang, the Authorities, or contested.

| Controller | Effect |
|---|---|
| Criminal gang | Businesses in district produce bonus output; gang collects protection; heat rises over time |
| Authority | District generates tax revenue and patrol incidents; criminal businesses inside suffer output penalty |
| Contested | Neither bonus; frequent incidents; open PvP zone |

### Changing control

- **Gang war (Criminal vs Criminal):** declared by a gang leader; capture-point contest over a timed window.
- **Lockdown (Authority vs Criminal):** declared by Mayor or captain; Authorities must complete a raid on the district's anchor business and hold checkpoints for a timed window.
- **Takeover (Criminal vs Authority):** a gang must run a successful heist inside the district and then hold it against response.

Both factions therefore have something to defend and something to take in every district.

---

## 10. Consequences: Arrest and Death

### Arrest (Criminal)

- Player is transported to jail. Sentence scales with rank and current charges (default 5–20 real minutes).
- Carried equipment and contraband are seized to the city budget.
- Bail can be paid from personal funds or war chest at a premium, halving the sentence.
- **Arresting the Kingpin removes the title.** This is the Authority faction's primary path to disrupting criminal leadership.

### Death

- Both factions: lose carried equipment, respawn at faction base after a short timer.
- Authorities additionally incur a budget fine (equipment replacement).

### Misconduct (Authority)

- Arresting a player with no active charges, or excessive civilian damage, incurs a fine and reduces commendations. Repeated misconduct can trigger an internal-affairs suspension (temporary rank lock).

---

## 11. Module Architecture

### 11.1 Core modules (ship together; the mode is complete with these)

| Module | Responsibility |
|---|---|
| **Player Progression** | XP, ranks, tier unlocks, season persistence |
| **Faction Hierarchy** | Configurable rank names/tiers; leadership eligibility rules |
| **Criminal Jobs** | Street-level jobs (theft, dealing, smuggling) |
| **Authority Jobs** | Patrol, dispatch incidents, basic investigation |
| **Mission Control** | Stage state machine shared by heists and raids; alerts; evidence |
| **Economy** | Currency, sinks, trading, war chest, city budget |
| **Territory** | District ownership, control changes, effects |
| **Leadership** | Kingpin challenge, Mayor election, powers, recall |
| **Consequences** | Arrest, jail, bail, death, misconduct |

### 11.2 Optional modules

| Module | Adds | Depends on |
|---|---|---|
| Infiltration | Dirty Cop / Mole roles, cover integrity, Internal Affairs, loyalty tests | Leadership, Mission Control |
| Heist Missions | Full heist target catalogue and prep chains | Mission Control |
| Raid Missions | Full investigation chains and raid targets | Mission Control |
| Business Management | Ownable, upgradeable criminal businesses | Economy, Territory |
| Advanced Criminal Jobs | Arms dealer, hacker, hitman | Criminal Jobs |
| Advanced Authority Jobs | Undercover, forensics, government agent | Authority Jobs |
| Black Market | Criminal item exchange | Economy |
| Casino & Gambling | Casinos as businesses and raid targets | Business Management |
| Gang War Expansion | Alliances, multi-gang wars, mercenary contracts | Territory |
| Reputation | Simple per-player rep score affecting NPC prices and mission access | Player Progression |

The v1 "Psychological Profile Module" is reduced to **Reputation**: one number, no branching morality system. A full behavioral/morality system is out of scope.

### 11.3 Module loading

Each module declares its name, version, and dependencies in a manifest. On server start, the core loader:

1. Reads all manifests in the resource folder.
2. Resolves dependency order; refuses to start with a missing dependency and logs which one.
3. Registers each module's event handlers and config.

This replaces v1's "scanning" language with a conventional dependency loader. Feature availability is a consequence of what is installed, not a runtime detection heuristic.

---

## 12. Technical Approach

- **Runtime:** FiveM / CitizenFX. Language choice is a real tradeoff:
  - **C# (mono runtime):** strong typing and tooling, matches the OOP design intent. Cuts off direct compatibility with the Lua framework ecosystem (ESX, QBCore, ox_*), meaning inventory, banking, and UI must be built in-house or bridged.
  - **Lua:** ecosystem compatibility and community familiarity; weaker tooling.
  - **Recommendation:** C# for core game logic where the OOP structure matters; expose Lua-facing exports for framework bridges so servers running QBCore/ESX can integrate. Decide before Phase 1 begins.
- **Persistence:** MySQL/MariaDB (the FiveM norm) via oxmysql or an equivalent. All faction state, territory, businesses, and season data server-authoritative.
- **Client trust:** all economy, mission stage transitions, and arrest logic resolve server-side. Clients report intent; the server validates.
- **Anti-cheat:** out of scope for this resource. Server owners use FiveM's built-in protections and third-party anti-cheat. The design does not claim to solve this.
- **Configuration:** a single `config` file per module (`.lua` or `.json`) exposes every tunable referenced in this document (season length, thresholds, timers, rates). This is the v1 customization surface.

---

## 13. Scope and Roadmap

### Phase 1 — Core (playable at 8 players)

- Player Progression, Faction Hierarchy, Economy, Consequences
- Criminal Jobs and Authority Jobs (street-level and patrol only)
- Territory with Authority/Criminal/Contested states
- Leadership with basic challenge and election
- Mission Control with **one** heist target and **one** raid target to prove the interaction

**Exit criteria:** a 4v4 session has something for everyone to do for two hours, and the leadership positions change hands at least once in a test season.

### Phase 2 — Depth

- Heist Missions and Raid Missions catalogues
- Business Management
- Gang wars and lockdowns as full timed contests
- Seasons with persistence rules
- Infiltration (needs the full heist/raid catalogues to have something worth leaking)

### Phase 3 — Breadth

- Advanced job modules, Black Market, Casino, Gang War Expansion, Reputation

### Deferred / re-evaluate after Phase 2

- **Web-based drag-and-drop configurator** that packages modules into a ZIP/7z. This is a separate product with its own maintenance burden and mostly duplicates what config files provide. Build only if there is demonstrated demand from server owners.
- **Official vs. non-official server verification.** Requires a hosted backend, license keys, and server-authoritative validation on infrastructure the project controls; file-size checks are not a meaningful tamper defense. Defer until there is a shared cross-server feature (global leaderboards, cross-server seasons) that actually needs it.

---

## 14. Open Questions

1. **Faction imbalance at runtime.** What happens when 10 criminals and 2 authorities are online? Candidates: NPC backfill for patrols, faction-switch incentives, a bonus multiplier for the minority faction. Needs prototyping.
2. **Alt accounts and vote manipulation.** Commendation-weighted voting mitigates but does not solve. Consider requiring minimum in-season playtime to vote.
3. **Off-hours raids.** Can Authorities raid a business whose owner is offline? Proposal: yes, but with reduced seizure and a mandatory notification; otherwise businesses are only vulnerable when it is inconvenient for the owner. Needs balance testing.
4. **Kingpin inactivity vs. time zones.** 72-hour inactivity should account for a configurable grace period and a designated deputy.
5. **Framework bridging cost.** How much of Phase 1 is spent building inventory/banking that QBCore already has? This may decide the language question.
6. **Infiltrator collusion.** Two friends in opposite factions could coordinate an infiltrator "exposure" to farm the counter-intel bonus. Cooldowns and the accuser penalty mitigate; monitor in testing.
7. **Infiltrator voice/chat.** Cover only works if the host faction can't see the infiltrator's true-faction comms. Faction chat channels must be keyed to *cover* faction, with a separate private channel to the true faction's leader.

---

## Appendix A — Changes from v1

| v1 | v2 | Reason |
|---|---|---|
| Authorities run legitimate businesses | Authorities govern districts via city budget | Gave the faction a real verb |
| No leadership loss mechanic | Challenge, election, recall, arrest, inactivity, season end | Power must be contestable |
| No session/reset model | Seasons with partial rank persistence | Prevents entrenchment |
| Income sources only | Explicit sink table with 60–70% burn target | Inflation control |
| Territory contested only between gangs | Every district always held by someone; three control-change modes | Both sides have stakes everywhere |
| Psychological Profile Module | Reputation score | Scope |
| "Anti-cheat and module scanning" | Dependency loader; anti-cheat declared out of scope | Honesty about what the system does |
| Webpage configurator and official-server backend as core features | Deferred to post-Phase 2 | Two side-products before the game is proven |
| C# presented as a feature | C# presented as a tradeoff with a recommendation | Ecosystem compatibility is a real cost |
| — | Infiltrators (Dirty Cop / Mole) with cover risk, Internal Affairs, loyalty tests | Hidden-role layer for the mid-game; makes planning secrecy a social system |