institution/Wiki/contraband/Home.md

# Institution: Contraband

*Prisoners get hold of things they should not have. Wardens turn the cell over looking for them.*

This is the player-facing wiki for **Institution: Contraband**, a RimWorld 1.6 mod. It documents
every mechanic with the real numbers pulled from the source, explains why each one works the way it
does, and tells you how to play with them — and against them.

> **Note on scope.** Contraband was recently *split*. It is now one thing: the **physical smuggling
> loop** of a prison. The engine it used to carry — propensity, the criminal record, the
> secured-context predicate — now lives in **Institution: Core**, which this mod requires. The
> response systems (classification, deterrence, discipline, parole, regime) went to **Institution:
> Justice**, and the gang network to **Institution: Gangs**. If this page mentions "the record" or
> "a pawn's propensity," those are Core's; Contraband reads them.

## The one idea

The whole Institution suite rests on a single sentence:

> **Every pawn has a criminal propensity on a spectrum — nature (traits) × nurture (circumstance,
> mood, treatment) — and the colony can police it.**

Contraband is the half of that sentence you can *hold in your hand*. A propensity is abstract until
a disposed prisoner files a blade off his bunk, palms a twist of yayo on the way into a cell, or
starts digging. Contraband is where the spectrum becomes an object with edges.

## Vanilla built the demand and forgot the supply chain

RimWorld already ships a fully-built junkie. Raiders spawn addicted (`chemicalAddictionChance`,
`forcedAddictions`) and carrying combat drugs (`combatEnhancingDrugsChance`). You down one, capture
strips everything (`DropAndForbidEverything`), and now withdrawal grips them in the cell
(`Need_Chemical`, `Hediff_Addiction`). A prisoner already *seeks* a drug on their own —
`JobGiver_SatisfyChemicalNeed` is in the prisoner think tree — and already *ignores* the forbidden
flag inside their own cell (`ForbidUtility.CaresAboutForbidden`).

Put a drug within reach of an addicted prisoner and the base game makes them take it. Today. With no
new code. The consumer, the craving, the reach, the ignore-forbidden — all of it ships.

What does **not** ship is any answer to two questions:

| Vanilla has | Vanilla lacks |
|---|---|
| A prisoner who wants contraband | Any route for contraband to reach the cell |
| A warden with fifteen jobs | A sixteenth called *search* |

Search `Assembly-CSharp.dll` for `Contraband`, `Search`, `Confiscate`, `Smuggle`, `Frisk`,
`Shakedown` and you get **zero types**. The warden can chat, convert, feed, execute, enslave,
release, suppress — and cannot look in a pocket. Contraband builds exactly the missing two halves:
**supply** and **search**. It does not need to build the junkie, because Ludeon already did.

## Concealment is a secret, not an item

This is the load-bearing design decision, inherited from Foul Play (the Piss Nuke) and kept:

> **While it is concealed, there is no `Thing`.**

A hidden shiv is not in the gear tab. There is no icon. There is no stack on a shelf. The player is
told **nothing**. The item exists only as a row in `MapComponent_Contraband`'s private list, and it
becomes a real `Thing` at exactly two moments:

- when the prisoner **uses** it (the secret is "redeemed" into their inventory), and
- when a warden **finds** it in a search (it is confiscated and never becomes a thing at all).

Why go to the trouble? Because *an item you can see in a UI is not contraband* — it's inventory, and
there would be nothing to discover and no reason to ever order a search. The whole tension of the
system is that **you never know**. A warden you send to toss a cell might find a blade, might foil a
tunnel, or might waste twenty minutes on a prisoner who was hiding nothing — and that empty search
still has to cost, or the mere *offer* of the job would be the discovery.

Read the full lifecycle in **Concealment and Intake**.

## The four supply routes and the one counter

| Route | What it is | Page |
|---|---|---|
| **Intake** | A captive hides the small contraband they walked in with | [Concealment and Intake](Concealment-and-Intake.md) |
| **Improvise** | Whittle a shiv from the cell's own furniture | [Improvised Weapons](Improvised-Weapons.md) |
| **Tunnel** | Dig out under the perimeter with a filed pick | [Tunnels](Tunnels.md) |
| **A bent warden** | A greedy or over-kind guard smuggles *for* a prisoner | [Corruption](Corruption.md) |
| **The counter** | A prioritized cell toss that reads the tells | [Warden Search](Warden-Search.md) |

And because every guard is a person with their own diligence and their own price, the search is only
as good as who you send — see **Corruption**.

## How everything is contraband without a list

Contraband names no items. It recognises three sources at load and logs the count:

1. **Anything carrying `CompProperties_Contraband`** — the explicit opt-in, with pluggable behaviour.
2. **Every drug** (`ThingDef.IsDrug`) — vanilla's, Vanilla Expanded's, mods that don't exist yet.
   Hard drugs conceal better (0.75 vs 0.5).
3. **Every weapon** (`ThingDef.IsWeapon`) — concealability and hiding place derived from **mass**. A
   knife rides on the body; a heavy gun goes under the floor; a minigun (over 10 kg) hides nowhere.

It is a lookup, not a patch. Nothing mutates another mod's defs. Details in
[Concealment and Intake](Concealment-and-Intake.md) and [Compatibility](Compatibility.md).

## Index

- **[Concealment and Intake](Concealment-and-Intake.md)** — the secret model, `ConcealSite`, the
  three sources, intake on capture, redemption, and the opaque content-tag bridge.
- **[Improvised Weapons](Improvised-Weapons.md)** — the shiv whittled from furniture, material
  carry-through, the damage tell, and who reaches for it in a breakout.
- **[Tunnels](Tunnels.md)** — the Prison-Architect dig under the perimeter, which pawns dig, and how
  a search uncovers the shaft.
- **[Warden Search](Warden-Search.md)** — the prioritized search, how tells and the record drive
  priority, what a search does, and how it writes back.
- **[Corruption](Corruption.md)** — Diligence and Corruption from traits and mood, how they scale a
  find, and the bent warden who looks away or smuggles in.
- **[Compatibility](Compatibility.md)** — the Core dependency, the Foul Play bridge, Justice/Gangs
  interplay, and the prison mods the suite is tested against.

## The suite

Each mod stands alone as an install; together they form one system.

| Mod | Owns | Depends on |
|---|---|---|
| **Institution: Core** | propensity, criminal record, secured context | base game |
| **Institution: Contraband** (this) | concealment, intake, shivs, tunnels, search, corruption | Core |
| **Institution: Justice** | classification, deterrence, discipline, parole, regime | Core |
| **Institution: Gangs** | gangs as contraband economies | Core, Contraband, Justice |
| **Foul Play** | vessel + substance + throw framework; the Piss Nuke; bridges its carboy in as contraband | standalone |
| **Ward** | a ward prison mode + the suite's test harness | — |

---

*Part of the **Institution** suite — Core · Contraband · Justice · Gangs, alongside Foul Play and
Ward. Each stands alone; together they interlock.*
**