flan/institution
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Player-facing wiki rewrite

flan
2026-07-16 02:19:04 +00:00
parent bf6825519c
commit 6491d2b341
9 changed files with 290 additions and 1062 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Compatibility.md
-116
@@ -1,116 +0,0 @@
# Compatibility
*Contraband adds its own content and reads from the base game rather than rewriting it. That is why it
composes with other mods instead of colliding with them.*
## Requires: Institution: Core
Contraband has a hard dependency on **Institution: Core** and loads after it. This is not optional —
after the split, everything Contraband reads lives in Core:
| Core provides | Contraband uses it for |
|---|---|
| Which pawns count as "in custody," and who can hide things | who counts as a concealer; who can be intaken, whittle, or dig |
| A pawn's criminal propensity (nature × nurture) | every disposition roll — intake (0.6), improvise (0.10), dig (0.08), all scaled and settled per pawn |
| The criminal record | times searched, times caught, escape attempts, contraband made — written by search and acquisition, read by search priority |
Install Contraband without Core and it will not run. Everything else on this page is optional interplay
that degrades gracefully when the other mod is absent.
## It plays nicely with other prison mods
Contraband adds its own content rather than rewriting the base game's. It:
- **Adds a new warden job** (search) rather than changing an existing one.
- **Reuses vanilla warden behaviour** rather than overriding it, so anything that adjusts warden
behaviour on the base class flows through to searches for free.
- **Extends two escape-related behaviours at startup** so prisoners arm themselves and use what they
are hiding when they break — inserted at a specific point, and it logs a warning if that anchor is
missing rather than failing silently.
- **Runs on a heartbeat** over held pawns for intake, improvisation, and tunnels — no hook on the
capture event is needed because the heartbeat already visits every held pawn.
The net effect: the surfaces other prison mods touch are mostly untouched here, so conflicts are the
exception, not the rule.
## Foul Play — the carboy bridge
**Foul Play** (the "Piss Nuke" mod) stays its own mod with its own front door, and yet its **carboy is
a first-class contraband item.** This is the flagship demonstration of Contraband's *"items are
content, subsystems are shared, mods are audiences"* principle, and it works two ways:
1. **The carboy brings its own behaviour.** The carboy simply declares itself as contraband and points
at the throw-the-carboy behaviour that lives in *Foul Play*. Contraband never has to know that
behaviour exists — it just runs whatever the item brought with it.
2. **A concealed carboy keeps its contents.** A carboy is not just "a jar" — it is a jar *of* a
fermented blend, and that blend has to survive being concealed. When a carboy is intaken or
smuggled, Contraband captures a label for its contents blindly; on redemption it hands the label
back to Foul Play to restore the blend. **Contraband knows nothing about substances or
fermentation** — that framework lives entirely in Foul Play. If Foul Play is absent, no content is
captured and nothing breaks: a jar is just a jar. See
[Concealment and Intake](Concealment-and-Intake.md).
The dependency runs one way only: Foul Play bridges *to* Contraband (and to Core) if they are present;
Contraband takes **no** dependency on Foul Play.
## Institution: Justice — the record is the shared bus
Contraband and **Justice** never call each other. They meet on Core's criminal record — Contraband
writes to it, Justice reads from it:
| Contraband writes | Justice reads it into |
|---|---|
| times searched | Classification (security grade) |
| times caught | Deterrence (colony-wide signal) |
| escape attempts | Discipline / Parole (reform) |
| contraband made | |
- **Catching contraband feeds classification.** A prisoner repeatedly caught with shivs or foiled
mid-tunnel racks up catches and escape attempts, which Justice's classification weighs into a higher
security grade.
- **And it feeds back.** Justice's deterrence signal flows *back* through Core's propensity, nudging
every future intake / improvise / dig roll a Contraband pawn makes. A prison that catches and
disciplines becomes a prison where fewer prisoners bother trying — without either mod referencing the
other. Run Contraband alone and deterrence is a neutral 1.0; the record still routes the warden.
## Institution: Gangs — the contraband economy
**Gangs** depends on Core, **Contraband**, and Justice, because a gang *is* a contraband economy:
- Gang smuggling moves contraband through the same door intake and corruption use.
- A gang's outside members are the natural caller for the **reach-in corruption** — paying a bent
warden to make a delivery. That ability exists in Contraband but has no in-game trigger of its own;
Gangs is what drives it. See [Corruption](Corruption.md).
- Gang fights route to Justice's crime record, which then raises search priority here. The loop closes
through Core again.
## Prison mods the suite is tested against
| Mod | Interaction | Verdict |
|---|---|---|
| **Prison Commons** | it adjusts warden behaviour on the base class, and Contraband's search inherits that, so searches respect prison-commons/allowed areas **for free** | works by inheritance |
| **Custom Prisoner Interactions** | it only touches the *named* vanilla warden jobs (chat, convert, enslave, release); it cannot see a brand-new job | no conflict |
| **Prisoner Realism** | its escapes are for "mood prisoners" mid-break; a tunnel breakout hands off to the vanilla prison-break flow, which Prisoner Realism layers on. Tunnels **complement** it — they let ward patients and slaves who would never mood-break still, patiently, dig out | complementary |
| **Prison Labor** | prisoners working outside the cell are still held pawns and still tracked; Contraband adds nothing to labor jobs. A work assignment is simply another place a disposed prisoner might come by materials | no conflict |
| **Prisoner Recreation** | overlaps the *regime* feature — which now lives in **Institution: Justice**, not here, and is written to coexist with Prisoner Recreation | not Contraband's concern post-split |
## Load order
1. Base game
2. **Institution: Core** — required, loads before Contraband
3. **Institution: Contraband** — this mod
4. **Foul Play / Justice / Gangs** — any order after Core; each bridges if present
## The general rule
If a mod adds prisoner behaviour by **changing vanilla warden jobs or the escape flow by name**, it
will not see Contraband's additions, and Contraband will not see its — they pass each other harmlessly.
If a mod adds a *new* warden job or escape behaviour of its own, it stacks. The one place to watch is
another mod that *also* rewrites the same two escape-related behaviours wholesale; Contraband inserts
its part at a specific point and logs a warning if that point is missing, so a load-order or conflict
problem is visible in the log rather than silent.
---
*Part of the **Institution** suite — Core · Contraband · Justice · Gangs, alongside Foul Play and
Ward. Each stands alone; together they interlock.*
Concealment-and-Intake.md
-201
@@ -1,201 +0,0 @@
# Concealment and Intake
*How a hidden item exists without existing, how it gets onto a prisoner in the first place, and how
it becomes real again.*
This is the spine of the whole mod. Everything else — shivs, tunnels, searches, corruption — is a
different way to add to, or remove from, the private stash this page describes.
## While it is concealed, there is no item
The single most important rule:
> The prison quietly tracks what each pawn is hiding. **Concealed contraband is not an item on the
> map. It is a secret.** It is not in the gear tab, there is no icon, and the player is told nothing —
> because an item you can see in the UI is not contraband, it is inventory, and there would be nothing
> for a warden to discover and no reason to ever order a search.
A concealed item is only a hidden fact about a pawn: what it is, how far along it is, what material it
ended up made of, an optional source it is being whittled from, its tunnel state if it is a pick, and
whatever it holds inside. It has **no physical object** anywhere in the world until one of two things
happens:
| Moment | What happens |
|---|---|
| The prisoner **uses** it | It materialises into their inventory as a real item |
| A warden **finds** it | It is deleted; it never becomes an item at all |
A corollary the search page leans on hard: **an empty search must still cost time.** If the search
job only ever appeared when there was genuinely something to find, the mere *offer* of the job would
be the discovery. You have to be able to toss a clean cell and come up with nothing.
## Where a thing can hide
Every piece of contraband can hide in one of two places, and this decides **who can ever find it**:
| Site | Holds | Found by |
|---|---|---|
| **On the body** | small: a shiv, pills, a phone | searching the **pawn** |
| **In the cell** | bulky: a rifle, a carboy, a crude pick | tossing the **room** |
A warden turning over a prisoner and their cell reaches both. The reason the two are split at all: a
**constable** in Justice's policing layer, frisking a colonist named in a street crime, only reaches
what is on the body, so whatever is under their floorboards stays there until somebody has grounds to
search the *room*. The split between "who may search" and "what a search reaches" is deliberate — see
[Warden Search](Warden-Search.md).
## Three kinds of contraband, and no list of items
There is no hardcoded list of contraband item names. At the start of a game, the mod looks at every
item in the game and decides, once, whether it counts as contraband, in one of three ways:
1. **Explicit.** Anything a mod has deliberately marked as contraband. This is the opt-in, and it is
how a mod plugs in its own behaviour for how the item is acquired, used, or used to escape.
2. **Every drug** — recognised automatically.
3. **Every weapon** that isn't destroyed when dropped — recognised from its **mass**.
For anything not marked explicitly, the mod fills in how well it hides and where, so a modder never
has to:
| Kind | Test | Concealability | Hides |
|---|---|---|---|
| Hard drug | drug rated Hard | **0.75** | on body or in cell |
| Other drug | any other drug | **0.5** | on body or in cell |
| Light weapon | mass ≤ 2.0 kg | **0.7** | on body or in cell |
| Heavy weapon | 2.0 kg < mass ≤ 10.0 kg | **0.35** | in cell only |
| Very heavy weapon | mass > 10.0 kg | — | **not contraband** (a minigun hides nowhere) |
**Concealability** runs 0 to 1, where **0 = a warden finds it every time and 1 = never**; higher is
harder to find. Drugs and inferred weapons get **no crafting route** (you cannot synthesise yayo in a
bare cell, and you cannot conjure a rifle) and **no special use behaviour** — because vanilla already
knows what to do with them. A prisoner takes a drug on their own; an armed prisoner *is* the payload.
Getting the item into the cell is the entire problem, and that is all these routes solve.
Nothing here edits another mod's items. It is a one-time reading of each item's own stats. Modded
drugs and weapons are covered without ever being named.
## The heartbeat
The prison does its ongoing work on a heartbeat. Every **250 ticks** it visits every pawn who could
be concealing something and does all the ongoing work: intake, tunnel progress, and improvisation. If
nothing on the map can be self-made and no escape tools are in play, it does nothing and costs
nothing.
Because the heartbeat already visits every held pawn, intake needs no special trigger on the capture
event: a pawn who is in custody but has not yet been processed is, by definition, one who was newly
taken.
### Who counts as a concealer
The set of pawns being tracked is **not** just prisoners. It is every pawn whose belongings are
anyone's business — prisoners, slaves, ward patients, **and free colonists**:
> A free colonist forbidden their drug by a drug policy or an ideoligion is precisely the pawn who
> keeps a private stash — and vanilla already denies them, with no valve.
Whether anyone may *search* a given concealer is a separate question with a separate answer (the
warden's authority reaches prisoners; a future cop's reaches colonists). Tracking is pawn-agnostic;
authority is not.
## Intake: the moment of capture
Vanilla never strips a captive *on capture* — a downed pawn keeps whatever they walked in with, and
the warden just hauls them to a cell. Intake is Contraband's answer to that gap, and it runs on the
first heartbeat that sees a newly-held pawn:
1. **Held only.** The pawn must be a person and in custody — prisoner, slave, or ward patient. A free
colonist is tracked, but nobody frisks and processes *them* on the way into a cell, so their
carried gear is never intaken.
2. **Once.** Each captive is processed a single time; a later pass finds them already done and moves
on. (It remembers by an ID, so it holds no ghost of a captive who has since died.)
3. **Even while downed.** Intake runs *before* the "must be awake" gate. The stash a captive walked in
with is hidden the moment they are in custody, not when they wake — everything *after* intake
(whittling, digging) needs them awake, but hiding what is already on you does not.
4. **Only what can ride on a body.** A thing can be intaken only if it is small enough to hide on the
body. A shiv up a sleeve is intaken; a rifle or a suit of armour is too bulky to palm and stays as
ordinary strippable gear the player confiscates for free.
5. **Per-item disposition.** For each concealable thing the captive carries, the mod rolls whether
*this* pawn would hide *this* item — a base chance of **0.6**, then scaled by the pawn's nature ×
nurture (Core's propensity). The roll is **fixed per (pawn, item)** — a settled fact, not a fresh
coin each tick. The frightened cook surrenders the knife; the disposed lifer palms it, and always
would have.
When a pawn does hide an item, the real object is **removed from the game** and a hidden secret takes
its place, preserving what the item was made of and — critically — anything it holds inside.
## Preserving contents without understanding them
A concealed vessel is not just "a jar" — it is a jar *of* something (hooch, piss, a fermented blend),
and that something has to survive being hidden and come back when the item is used. Contraband stores
what a vessel contains as a single opaque label and **has no idea what it means**.
When the item is concealed, that label is captured; when the item comes back out, the label is used
to pour the contents back into the freshly-made thing. This is the exact seam **Foul Play** uses to
keep a smuggled carboy's contents intact. Without a bridge mod, no content is captured and nothing is
lost — a shiv is just a shiv.
Fermentation itself lives in Foul Play, not here. A concealed vessel comes back out **fresh** and
ferments afterward like any other, which suits the theme: fresh-brewed piss is weak, and time is what
makes it a weapon. (The prison remembers how long the vessel was hidden, for any bridge mod that
wants to restore its aging, but it never acts on that number itself.) See
[Compatibility](Compatibility.md).
## Redemption: the secret becomes real
When a hidden item is finally used, it turns real:
1. It is made from the material it was whittled from (or the item's default material, if it was never
made from a material).
2. Anything it held inside is poured back in.
3. It is placed into the pawn's inventory. If that somehow fails, nothing is dropped and nothing is
lost.
4. The secret is cleared from the stash.
The trigger for this is a breakout. When a prisoner enters an escape or assault-the-colony state, they
will arm themselves and then use whatever they are hiding — the same moment a base-game prisoner would
reach for a combat drug. The one contraband hook Ludeon wrote and then left reading an always-empty
inventory is exactly where this slots in. For each thing a pawn is hiding:
- **Inert contraband** (a drug, a stashed rifle — nothing special to "use"): just materialise it and
get out of the way. Vanilla takes the drug on its own; a weapon in inventory is a weapon. But a
stashed **weapon** only comes out for someone who would actually use it — the same person who would
not stop to pick a rifle off the floor does not become a fighter because the knife was in their
sock, and a pawn incapable of violence never does at all. If they qualify, the weapon moves into
their hands; otherwise it stays hidden and they run. See [Improvised Weapons](Improvised-Weapons.md).
- **Active contraband** (something with a special use — e.g. Foul Play's throw-the-carboy):
materialise it, then hand off to that item's own use behaviour.
## Confiscation, and the door every route comes through
When a warden finds contraband, it is simply removed. It **never becomes a real item** — the warden
found it, and there is nothing to drop on the floor. (This is why searching is not a way for the
colony to *acquire* a prisoner's drugs; it is a way to *deny* them.)
At the other end, there is one single door that **every** supply route comes through — intake uses it,
a bent warden uses it ([Corruption](Corruption.md)), and a smuggling gangmate
([Institution: Gangs](Compatibility.md)) uses it. It hands a prisoner something already finished and
hidden, optionally with contents. One door, many keys.
## Saving
Concealed contraband is saved with your game — the whole stash, the per-pawn search cooldowns, and who
has already been intaken. On load, any secret whose pawn or item no longer exists is quietly dropped:
prisoners who died or left take their secrets with them.
## Quick reference
| Constant | Value | Meaning |
|---|---|---|
| Heartbeat | every 250 ticks | poll cadence for intake / tunnels / improvisation |
| Intake base chance | 0.60 | per-item, before nature × nurture |
| Intake gate | held + body-hideable | only pawns in custody, only items small enough to palm |
| Hard-drug concealability | 0.75 | inferred from being a hard drug |
| Other-drug concealability | 0.50 | inferred |
| Light-weapon concealability | 0.70 | mass ≤ 2.0 kg, hides on body |
| Heavy-weapon concealability | 0.35 | 2.0–10.0 kg, in cell only |
| Unhideable mass | > 10.0 kg | not contraband |
---
*Part of the **Institution** suite — Core · Contraband · Justice · Gangs, alongside Foul Play and
Ward. Each stands alone; together they interlock.*
Corruption.md
-111
@@ -1,111 +0,0 @@
# Corruption
*A search is only as thorough as the warden running it, and a warden is a person with their own
diligence and their own price.*
The counter to contraband is the [warden search](Warden-Search.md) — but a search is not a machine. It
is a human being with traits and a mood, and Contraband models that human being on **two axes, both
read off the same vanilla traits, mood, and relationships — no new stat to maintain**:
| Axis | Question | Effect on a search |
|---|---|---|
| **Diligence** | How hard do they look? | multiplies the find chance |
| **Corruption** | How bent are they? | a flat chance to look away — and a route *into* the prison |
This is *"what turns 'the game vs the player' into 'the player's own guards, each with an angle.'"* The
prisoner you can control. The guard you assigned to watch them, you cannot.
## Diligence — how hard they look
Diligence runs 0 to 1 and multiplies the whole find chance. A lax or miserable warden misses things a
dutiful one would turn up. It starts from a baseline of **0.55** and moves with traits and mood:
| Trait / factor | Δ Diligence | Reasoning |
|---|---|---|
| Industrious | +0.1 per degree | a hard worker searches hard |
| Lazy | −0.1 per degree | a lazy one frisks gently |
| Abrasive | +0.15 | happy to toss a cell |
| Psychopath | +0.10 | thoroughness without squeamishness |
| Kind | −0.20 | reluctant to be rough |
| Mood | ×0.6 (miserable) .. ×1.1 (content) | morale is thoroughness |
## Corruption — their price
Corruption also runs 0 to 1. In a search, a bent warden gets a flat chance to **look away** on each
item they would otherwise have a shot at finding — that chance is their Corruption × 0.6, rolled per
hidden item before the find roll. Corruption starts from a baseline of **0.04** (most guards are
mostly honest) and moves with traits and mood:
| Trait / factor | Δ Corruption | Reasoning |
|---|---|---|
| Greedy | +0.40 | the classic bent guard — everyone has a number |
| Kind | +0.15 | looks the other way out of sympathy, not money |
| Ascetic | −0.10 | wants nothing, so cannot be bought |
| Abrasive | −0.05 | too surly to do anyone a favour |
| Mood | ×1.6 (miserable) .. ×0.7 (content) | a happy guard is harder to tempt |
## The Kind warden is a double liability
Read the two tables together and one trait jumps out. **Kind** *lowers* Diligence (−0.20) **and**
*raises* Corruption (+0.15). The gentle guard both frisks softly and bends the rules out of pity — the
worst warden you can put on a contraband detail, and the least obvious one, because "kind" reads as a
virtue everywhere else in the game. Meanwhile **mood** cuts the same way on both axes: a miserable
warden looks *less* hard and is *more* temptable. A depressed guard is a sieve at both ends.
## Worked examples
Find chance for a hidden item is roughly the base find chance × Diligence, with a separate look-away
chance (Corruption × 0.6) to ignore it entirely. Assume a mid-skill warden whose raw find chance on a
shiv is around 0.30 before disposition:
| Warden | Diligence | Corruption | Look-away/item | Net on a 0.30 shiv |
|---|---|---|---|---|
| Neutral, content | ~0.61 | ~0.03 | ~2% | thorough-ish: ~0.18 find |
| Abrasive + Psychopath, content | ~0.88 | ~0.02 | ~1% | a nightmare for prisoners: ~0.26 find |
| Greedy, content | ~0.61 | ~0.31 | ~18% | looks capable, pockets bribes |
| Greedy, **miserable** | ~0.37 | ~0.62 | ~37% | ignores contraband over a third of the time |
| Kind + **miserable** | ~0.25 | ~0.27 | ~16% | a sieve at both ends: ~0.07 find |
(Numbers rounded; mood taken as content ≈ 100% or miserable ≈ 20%.) The takeaway is that **who you
assign to search matters as much as whether you search at all.** A greedy, miserable warden is not a
guard — he is a supply line you are paying to pretend otherwise.
## The bent warden as a supply route *in*
Corruption is not only "looks away." The other half is reaching *in* — a bent guard who slips a
prisoner contraband through the very same door a smuggler or a gangmate uses. Only what can ride on a
body gets slipped across a handshake. Whether and when a guard does this is gated on that guard's
Corruption.
In Contraband on its own, this "smuggle in" ability exists but is not yet wired to an in-game trigger.
It is the seam **Institution: Gangs** drives when a gang's outside members pay a bent warden to make a
delivery, and the thing a planned secure-zone checkpoint that frisks *guards* is meant to catch.
Search-side corruption (looking away) is fully live today; reach-in corruption is the hook the rest of
the suite plugs into. See [Compatibility](Compatibility.md).
## How to play with it
- **Vet your wardens.** A Greedy or Kind pawn on prison duty is a liability the trait tooltip won't
warn you about. Ascetic and Industrious make the best searchers; Psychopath and Abrasive are
brutally effective if you can stomach them.
- **Watch mood.** A prison-duty warden in a slump is failing at both jobs — searching *and* not
smuggling. Keep your guards content or rotate them out.
- **Redundancy beats brilliance.** Because each search is one shot per prisoner per day and even a good
warden misses a well-hidden shiv, a *second* diligent warden over time matters more than a single
perfect search.
## Quick reference
| Constant | Value | Meaning |
|---|---|---|
| Diligence baseline | 0.55 | before traits and mood |
| Corruption baseline | 0.04 | most guards are mostly honest |
| Diligence mood scale | ×0.6 .. ×1.1 | miserable → content |
| Corruption mood scale | ×1.6 .. ×0.7 | miserable → content |
| Look-away multiplier | ×0.6 | applied to Corruption, per item |
| Smuggle payload | body-hideable contraband only | what fits in a handshake |
---
*Part of the **Institution** suite — Core · Contraband · Justice · Gangs, alongside Foul Play and
Ward. Each stands alone; together they interlock.*
Deterrence.md
+130
@@ -0,0 +1,130 @@
# Deterrence — the feedback loop
*The connection that turns the pipeline into a cycle.*
This is the part that makes policing **govern** rather than merely clean up. Everything else in Justice
reacts to one pawn: this reacts to the *whole colony*, and it feeds **back** into every pawn's
disposition. Crime that goes unanswered emboldens everyone a little; visible justice deters everyone a
little. The reason to punish is not just this prisoner — it is the message it sends the rest, and here
that message is a number they all read.
---
## The climate of order
Every colony carries one order value:
| | |
|---|---|
| **Range** | 0.0 (lawless) … 1.0 (iron) |
| **Baseline** | 0.5 — an ordinary colony |
| **Below baseline** | crime pays; dispositions run **hot** |
| **Above baseline** | order holds; dispositions run **cool** |
It is nudged by two events and, left alone, forgets.
### The nudges
| Event | Nudge |
|---|---|
| A crime, unanswered | **−0.08** |
| Visible justice done (a punishment) | **+0.12** |
Both stay clamped to the 0–1 range. Note the asymmetry: **punishment (+0.12) outweighs crime (−0.08)
by 1.5×.** A colony that answers every offence does not merely break even — it ratchets *above*
baseline into "order holds" territory. This is the deterrence dividend, and it is deliberate: justice
seen to be done buys more order than the crime cost.
The same crime that moves the climate also marks the culprit's record — the offence that shifts the
colony's mood is the one classification and parole will remember later. A punishment moves only the
climate; the reform side of a punishment — how the offender themselves changes — is
[Discipline](Discipline-and-Reform.md)'s job.
### The drift
Memory fades. With nothing happening, the climate creeps back toward ordinary at about **0.0015 every
in-game while (roughly one nudge every 2500 ticks)** — which works out to:
**drift per in-game day ≈ 0.036**
So a single unanswered crime (−0.08) takes roughly `0.08 / 0.036 ≈ 2.2 days` to heal on its own — or
one punishment (+0.12) to over-answer instantly. An iron colony you stop maintaining slides back to
baseline over about two weeks; it does not stay stern for free.
---
## The feedback — how it reaches every pawn
This is the loop. The climate is read back into every colonist's upbringing as a multiplier on their
propensity:
| Order level | Factor | Effect on every pawn's disposition |
|---|---|---|
| 0.00 (lawless) | **1.300** | +30% hotter — crime pays, everyone feels it |
| 0.30 | 1.120 | +12% |
| **0.50 (baseline)** | **1.000** | **neutral — a default colony sits exactly here** |
| 0.70 | 0.880 | −12% |
| 0.90 | 0.760 | −24% |
| 1.00 (iron) | **0.700** | −30% cooler — order holds, everyone calms |
Two things to notice:
- **Baseline is the neutral point, by design.** A default colony sits at 0.5, which is a factor of
exactly 1.0 — ordinary order neither inflames nor calms. That symmetry is deliberate. If baseline
ran hot, ordinary order would nudge propensity up, breed a little more crime, drop order, and feed a
slow runaway. Neutral-at-baseline means only a colony that lets order *slide below* ordinary earns
the hot multiplier, and only one that pushes *above* it earns the calm.
- **The swing is 0.7× to 1.3×, symmetric around 1.0** — a ±30% spread applied to *everyone's*
disposition at once. This is the multiplier that makes catching one pawn matter to the disposition of
the rest.
### When it applies
This bending of behaviour only happens while **Policing is installed**. Core on its own reads a flat,
neutral 1.0 — colonists are indifferent to order — and only Policing wires the climate into their
disposition. A colonist who is off the map (in a caravan, in transit) has no local climate to read, so
they fall back to neutral too.
---
## Worked example — a day at the institution
The colony starts at baseline 0.5 (factor 1.05). Over one day:
| Step | Event | Order level | Factor |
|---|---|---|---|
| start | — | 0.50 | 1.050 |
| 1 | Prisoner A shanks a guard (crime, unanswered) | 0.42 | 1.106 |
| 2 | Prisoner B foments trouble (crime, unanswered) | 0.34 | 1.162 |
| 3 | Warden punishes A | 0.46 | 1.078 |
| 4 | Warden punishes B | 0.58 | 0.994 |
| overnight | nothing happens, drift ≈ −0.036 toward 0.5 | 0.544 | 1.019 |
Two crimes cost −0.16; two punishments returned +0.24. The colony ends the day at 0.58 — **above**
where it started — because punishment out-answers crime. Every pawn's disposition dipped hotter as the
crimes landed (1.05 → 1.16) and then cooled below neutral once order was reasserted (0.994). By morning
the drift has begun erasing the gain, and if nothing keeps the pressure on, the colony sinks back to its
slightly-hot baseline over the next couple of weeks.
That arc — hot when crime pays, cool when justice is seen, forgetful when neither happens — is the
whole reason discipline is not inert. You are not punishing a pawn; you are setting the temperature of
the room.
---
## How to play with deterrence
- **Answer crime, visibly and promptly.** Each punishment is worth 1.5 crimes of order. A colony that
reliably punishes climbs *above* baseline and cools everyone; a colony that lets offences slide
sinks below and heats everyone — a spiral, because hotter pawns commit more crime.
- **Don't coast on a past crackdown.** The climate drifts back to baseline at 0.036/day. Order is a
maintenance cost, not a one-time purchase.
- **Push past baseline if you want calm.** Neutral disposition needs an order level of about 0.571;
ordinary (0.5) still runs 5% hot. A steady rhythm of caught-and-punished offences is what holds you
there.
- **A lawless spell is self-feeding.** At an order level of 0.3 every pawn is 1.19× more disposed; more
crime follows, driving the level lower still. Break the cycle with punishments, not patience.
---
*Part of the **Institution** suite for RimWorld 1.6: Core · Contraband · Policing · Corrections · Gangs · Ward.*
Home.md
+46 -119
@@ -1,126 +1,53 @@
# Institution: Contraband
# Institution: Policing
*Prisoners get hold of things they should not have. Wardens turn the cell over looking for them.*
*The enforcement and order layer — the pre-arrest half of the law — of the **Institution** suite of
RimWorld 1.6 mods.*
This is the player-facing wiki for **Institution: Contraband**, a RimWorld 1.6 mod. It documents
every mechanic with the real numbers, explains why each one works the way it does, and tells you how
to play with them — and against them.
Vanilla RimWorld keeps a rap sheet no one reads, and your own colonists never break the law. Policing
gives the colony a **climate of law and order**: colonists offend on a spectrum of criminal
propensity, the law catches them, and catching one changes how the rest behave.
> **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 — a pawn's criminal propensity, the criminal
> record, and which pawns count as "in custody" — 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**. When this page mentions
> "the record" or "a pawn's propensity," those belong to Core; Contraband reads them.
> **Catching and punishing one pawn changes the disposition of the rest.**
## 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 and carrying combat drugs. You
down one, capture strips everything, and now withdrawal grips them in the cell. A prisoner already
*seeks* a drug on their own, and already *ignores* the forbidden flag inside their own cell.
Put a drug within reach of an addicted prisoner and the base game makes them take it. Today. The
consumer, the craving, the reach, the ignore-forbidden — all of it already works.
What does **not** exist 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* |
The base game's 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:
> **While it is concealed, there is no item.**
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 does not become a real object in the world until exactly two moments:
- when the prisoner **uses** it (it appears in their inventory), and
- when a warden **finds** it in a search (it is confiscated and never becomes an item at all).
Why go to the trouble? Because *an item you can see in the 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](Concealment-and-Intake.md)**.
## 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](Corruption.md)**.
## How everything is contraband without a list
Contraband names no items. It recognises three kinds of thing:
1. **Anything explicitly marked as contraband** — the opt-in, with pluggable behaviour a mod can
supply.
2. **Every drug** — vanilla's, Vanilla Expanded's, mods that don't exist yet. Hard drugs conceal
better (0.75 vs 0.5).
3. **Every weapon** — how well it hides, and where, is decided by its **mass**. A knife rides on the
body; a heavy gun goes under the floor; a minigun (over 10 kg) hides nowhere.
It reads the item's own stats rather than editing anything. Nothing changes another mod's items.
Details in [Concealment and Intake](Concealment-and-Intake.md) and [Compatibility](Compatibility.md).
## Index
- **[Concealment and Intake](Concealment-and-Intake.md)** — the secret model, where a thing can hide,
the three kinds of contraband, intake on capture, redemption, and how a smuggled vessel keeps its
contents.
- **[Improvised Weapons](Improvised-Weapons.md)** — the shiv whittled from furniture, how its
material carries 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 feeds 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 | — |
That is the difference between enforcement that *cleans up* and enforcement that **governs** — the
reason to punish an offender is the message it sends everyone else quietly deciding whether crime pays.
---
*Part of the **Institution** suite — Core · Contraband · Justice · Gangs, alongside Foul Play and
Ward. Each stands alone; together they interlock.*
## The pages
| Page | What it covers |
|---|---|
| **[Policing](Policing.md)** | Colony crime on the propensity spectrum, witnesses and the constable's investigation, the weighed arrest and resisting it, prison riots, and the recidivism alert. |
| **[Deterrence](Deterrence.md)** | The colony's climate of order (0 lawless … 1 iron), moved by crime and punishment, drifting back to baseline, and fed back into every colonist's disposition. |
The climate of order only steers your colonists while Policing is installed. Core on its own keeps the
records but leaves behaviour untouched; add Policing and the feedback loop comes alive — visible
justice starts calming the colony, unanswered crime starts emboldening it.
---
## The one shared record
Policing keeps no crime record of its own. It reads and writes the single criminal record that
**Institution: Core** holds for every colonist — the same rap sheet Contraband, Corrections, and the
gang systems read. A crime here adds to that record; Corrections grades and reforms over the same
history.
---
## Requirements & load order
- **RimWorld 1.6**
- **Institution: Core** — required (the propensity and record system)
- **Harmony** — required
- Load **after** Core and Harmony.
The prison half — classification, discipline, reform, parole, regime — lives in **Institution:
Corrections**, which depends on this layer for the shared climate of order. A future **Judiciary** layer
— a court that tries and sentences — is planned; for now an arrest sends the culprit straight to a cell.
---
*Part of the **Institution** suite for RimWorld 1.6: Core · Contraband · Policing · Corrections · Gangs
· Ward. Split out of the former Institution: Justice.*
Improvised-Weapons.md
-176
@@ -1,176 +0,0 @@
# Improvised Weapons
*The supply route you cannot deny — because you are obliged to furnish the cell, and the furniture is
the raw material.*
You have to give a prisoner a bed. RimWorld will nag you until you do. That bed is a frame of wood, or
steel, or — if you built a nice prison — plasteel. Give a disposed prisoner a season of unsupervised
time with it and they will file a blade off it. **The prison's own furnishings are the arsenal, and
better furniture is worse.**
## The shiv
The shiv is a crude stabbing weapon: *"A blade filed off a bed frame and wrapped in cloth for a grip.
Barely a weapon — but a barely-a-weapon in a cell you thought was empty is a dead guard."*
| Stat | Value |
|---|---|
| Tech level | Neolithic |
| Mass | 0.4 kg |
| Concealability | **0.75** (hides very well — it rides on the body) |
| Hides | on body or in cell |
| Point (Stab) | power 7, cooldown 1.5 s |
| Handle (Blunt) | power 5, cooldown 1.6 s |
| Use | none — an armed prisoner *is* the payload |
Its stats come from its material: it can be made of metal, wood, or stone. A wood shiv is feeble; a
plasteel one is vicious. That is the whole point of the harvest mechanic — you never furnished a cell
thinking of it as an armoury, but that is what it is.
## Who whittles: the disposition gate
Not just "any prisoner." Three things must all be true:
1. **Held.** The pawn is a prisoner, slave, or ward patient. Free colonists do not whittle shivs in
the commons — *yet* (the concealment layer already tracks them; only the authority to act on them
is missing).
2. **Disposed.** A base chance of **0.10**, scaled by Core's nature × nurture. It is a *fixed fact*
about the pawn — the mistreated, high-propensity lifer chews his bed apart; the frightened cook
never does, and never would have, no matter how many times you reload.
3. **Material in reach.** There is a workable source (see below).
The base is deliberately low. Most prisoners are not making weapons. When one is, that is a fact about
*who they are and how you keep them*, and the tell it leaves is meant to point you at exactly that
pawn.
## The source: what counts as raw material
The prisoner looks for the nearest reachable, damageable, usefully-made piece of furniture:
- **Their own assigned bed first** — it is right there in the cell.
- Otherwise the **closest artificial building within 12 tiles** that qualifies.
To be a workable source, a piece of furniture must be:
| Requirement | Why |
|---|---|
| Made of a material | you cannot whittle a blade out of nothing |
| Damageable | it has to take a beating |
| Made of metal, wood, or stone | cloth and leather cannot be filed into a blade |
| Reachable, even through danger | they have to get to it |
This is also the counter-play. A cell furnished only in cloth and hydroponics offers nothing to file.
A steel bed offers a steel shiv. **What you build the cell out of decides whether it can become a
weapon, and how nasty that weapon is.**
## Harvest by damage: the tell *is* the mechanic
Each heartbeat, a whittling prisoner chips at the source — roughly **1.2% of its max hit points per
worked poll**, as blunt damage.
The damage is not a side effect — it is the point. A gnawed bed is **probable cause**. The same tick
that advances the shiv damages the furniture, and that visible wear is what
[Warden Search](Warden-Search.md) reads to send a guard to the *right* prisoner first: a badly damaged
bed shoots a prisoner to the top of the search priority list. Whittling a shiv is loud, in the only
sense that matters — it leaves a mark you can act on.
Because the source takes real damage, a determined prisoner can **reduce a piece of furniture to
wreckage and move on to the next**: if the source is destroyed before the shiv is finished, they look
for another, and if there is none, the route **stalls** (progress is kept, not lost). A materially
poor cell is a real defence — the prisoner cannot make progress with nothing to file.
## How long, and the material it becomes
A shiv takes roughly **1.5 unsupervised days** of active work, jittered ±25% each poll so no two
shivs finish on the same schedule.
When it is finished, it happens **silently** — the player is told nothing. Two things happen:
- **Material carry-through.** The shiv is made of whatever the source was made of. A wood bed yields a
wood shiv, a plasteel bunk a plasteel one, and its combat stats follow.
- **The record.** The pawn's tally of contraband made ticks up (in Core's record). That number feeds
the warden's future suspicion of this pawn and, if you run **Institution: Justice**, their security
classification.
## The shiv comes out in a break — and who reaches for it
A hidden shiv is inert until a breakout. When a prisoner enters an escape or assault-the-colony state,
they will use what they are hiding — but a **weapon** only comes out for someone who would actually
use it. That is the same test that decides whether an escapee even bothers to pick a weapon off the
floor.
This matters because **vanilla escapees never arm themselves at all.** The base game has the behaviour
for opportunistically grabbing a weapon, and simply leaves it out of the escape flow, so a base-game
prisoner walks out unarmed, always. Arming is genuinely new behaviour, so it is kept rare enough that
when it happens you recognise *who* did it.
### Would this pawn arm itself?
First a **hard gate**: a pawn who is incapable of violence never arms, ever — a pacifist who picks up
a rifle is not a rare event, it is a bug. Otherwise the chance is the pawn's **disposition** (who they
are, fixed) times their **circumstance** (what is happening right now), capped at **0.85** and settled
once per pawn as a fixed fact.
**Disposition** — who they are, fixed, nothing about today changes it. A base of 0.10, scaled by trait
and skill:
| Factor | Value |
|---|---|
| Bloodlust | ×2.5 (highest applicable trait only — not a stack) |
| Psychopath | ×2.0 |
| Brawler | ×1.8 |
| Wimp | ×0.3 |
| Kind | ×0.4 |
| skill | scales with their best of Shooting or Melee → range **0.5 .. 2.0** |
*Being captured in a raid does not make someone a fighter* — plenty of prisoners are cooks and
conscripts. A weapon is only worth grabbing if you know what to do with it, hence the skill term.
**Circumstance** — what is happening right now, live:
| Condition | Effect | Reasoning |
|---|---|---|
| Health < 50% | ×0.4 | badly hurt people run or crawl; they don't seek a fight |
| ≥ 2 other prisoners escaping within 12 tiles | ×2.0 | a crowd emboldens; one man slips out, six men riot |
| An armed colonist within 20 tiles | ×1.8 | now a weapon is not bravado, it's the plan |
### Which weapon they reach for
An arming escapee prefers, in order:
1. **Their own dropped weapon** — the gun they carried when you downed them, still lying where it fell
within 45 tiles. The base game remembers where it fell and then never uses that for prisoners. *"A
man walking back to the spot where his own rifle fell is a better story than a man rummaging through
your stockpile."* A prisoner does not care that you marked it forbidden.
2. **Anything to hand** within 18 tiles — but only for a pawn over a higher disposition floor (0.35).
Rummaging a stockpile is a further step than grabbing your own gun back.
A concealed shiv slots into this the natural way: a prisoner who has been sitting on a blade and who is
the sort to use it does not leave it in his pocket — it goes straight into his hand. The pawn who
would *not* arm keeps it hidden and runs — and the shiv survives to be found in a later search, or
used in a later break.
## Not only shivs: the crude pick
The same whittling behaviour makes the **crude pick** — filed off furniture exactly the same way, with
the same disposition gate and the same damage tell — but its purpose is a tunnel rather than a fight.
See [Tunnels](Tunnels.md).
## Quick reference
| Constant | Value | Meaning |
|---|---|---|
| Improvise base chance | 0.10 | before nature × nurture; fixed per pawn |
| Damage per worked poll | ~1.2% of source max HP | blunt; the visible tell |
| Source search radius | 12 tiles | own bed first, then nearest workable furniture |
| Time to finish a shiv | ~1.5 active days | jittered ±25% per poll |
| Workable material | metal / wood / stone | cloth and leather cannot be whittled |
| Shiv concealability | 0.75 | hard to find on the body |
| Arm chance cap | 0.85 | after disposition × circumstance |
| Own-weapon reach | 45 tiles | their dropped weapon |
| Any-weapon reach | 18 tiles | scavenge floor 0.35 disposition |
---
*Part of the **Institution** suite — Core · Contraband · Justice · Gangs, alongside Foul Play and
Ward. Each stands alone; together they interlock.*
Policing.md
+114
@@ -0,0 +1,114 @@
# Policing — the pre-arrest half
*The other half of the loop. Where the rest of Justice deals with people the colony has already
caught, **policing** is what happens before the cell door: your own colonists commit crimes on the
propensity spectrum, the colony investigates, and — sometimes — arrests.*
It is a big behavioural change (your colonists become potential criminals), so it has **its own
toggle** in the mod settings, on by default. Turn it off to run the rest of Justice — classification,
deterrence, discipline, parole, regime — without colony crime.
---
## The loop
**crime → witnessed / investigated → weighed arrest (resist?) → prison → … → parole → recidivism**
Every stage draws on the same shared systems — each colonist's propensity, the one shared criminal
record, the climate of order — so policing is not a bolt-on: the record it writes is the record
classification grades on and discipline reforms.
## Crime — and why small colonies stay honest
Every ~40 seconds, each free colonist gets a hidden roll to offend. The base chance is low (about
6% per roll) and it is multiplied hard by nature × nurture — almost nobody with an ordinary
disposition ever does anything. But it is *also* multiplied by **crime cover**:
| Free colonists | Crime cover |
|---|---|
| ≤ 3 | 0.15 |
| ~8 | ~0.6 |
| ≥ 13 | 1.0 |
In a tight 2–3 pawn colony everyone knows everyone and retribution is certain even without a jail, so
crime is **rare**; a larger, more anonymous colony offers cover. This is a deliberate inversion of the
naive "no enforcement → more crime": a small colony is kept honest by its own closeness, not by a
constable.
A crime is one of **theft**, **vandalism**, or **assault** — leaning on who the culprit is (a
kleptomaniac steals, a bloodlusty pawn assaults, a pyromaniac vandalizes).
## Consequences — the stakes
A crime leaves a mark the colony can *see*:
- **Theft** lifts a small stack of the colony's goods and the thief **pockets it**. RimWorld has no
per-person property (stockpiles are communal), so theft is theft from the common store — but the
culprit now physically carries what they took, a natural evidence trail a search can pick up.
- **Vandalism** damages a nearby colony building.
- **Assault** gives a nearby colonist a light, down-safe knock — and the culprit chooses their mark
**wisely**: someone they resent (motive), who is weak (little retribution), and unwatched (few
witnesses).
- **Relationships fray.** An assault victim thinks much worse of their attacker immediately (they saw
who did it); and when investigation *names* a culprit, the whole colony's opinion of them drops.
- The colony is **notified** a crime happened — culprit unknown.
## Witnesses and investigation
A crime is not equally solvable. Colonists who were near enough to **see** it are witnesses, and each
is a partial lead — a witnessed crime starts up to 80% of the way to solved before anyone lifts a
finger; an unseen one is a **cold case** worked from nothing.
Investigation then builds evidence toward a full, named solve two ways:
- **Ambient** progress, scaled by how many colonists the colony can spare — a background trickle from
everyone keeping an eye out, faster when the colony has people to spare.
- **The policing work type.** Assign a colonist to *policing* and they walk to open **crime scenes**
and work them, adding a chunk of evidence scaled by their Intellectual + Social skill. A sharp
constable cracks cases fast; a colony that spares no one lets them go cold.
## The weighed arrest
A solved case does **not** mean an automatic arrest. Fellow-colonist cops will not gut the colony to
jail someone over a petty crime — the arrest is a cost/benefit call, and it goes ahead only when both
are true: the colony can **afford a prison**, and the crime is **serious enough** to clear a bar that
rises with how valuable the culprit is.
- **Severity** — the crime's kind (theft 1 · vandalism 1.5 · assault 2.5), escalated by the culprit's
record (a rap sheet and prior escapes compound).
- **Value** — 0..1 from the culprit's best skills. The bar sits at about 1.5 for an expendable pawn
and climbs by three times the culprit's value — so a star colonist raises it to about 4.5.
- **Capacity** — **below ~5 colonists, or with no prison bed, the colony arrests no one.** A prisoner
plus a warden would cripple a small colony. Capacity ramps up as the colony grows.
So a petty crime by your only doctor → they walk. A murder → arrested regardless. And a crime that
paid, unanswered, erodes the climate of order a little more (crime emboldens).
## Resisting arrest
The disposed do not go quietly (seeded by nature × nurture):
- **Comply** → taken in cleanly (they become a prisoner of the colony — imprisonment is direct, and it
survives guest-management mods like Hospitality).
- **Resist** → the violent turn **berserk**, the rest **flee**. A botched arrest becomes a crisis the
colony must handle the hard way, and openly defying arrest emboldens the lawless.
- **Subdued** → a resister the colony beats down is then **imprisoned** — the resist path resolves to a
cell once the colony wins the confrontation. One who flees the map gets away.
## Prison riots
When the climate of order **collapses** (deterrence at the floor) in a colony holding prisoners, a
neglected prison boils over into a **riot**: disposed prisoners turn violent together, and the unrest
shatters order further. A well-run colony (high deterrence) never sees one — a riot is the thing a
badly-run institution *earns*.
## Recidivism, made visible
The loop closes on itself: a pawn hardened in prison (negative reform) runs a higher propensity and
reoffends. When investigation names a culprit the colony had **paroled**, it says so out loud — the
recidivism loop turning in the open, the payoff for everything classification, discipline, and parole
did upstream.
---
Part of **Institution: Policing**, in the Institution suite.
Tunnels.md
-158
@@ -1,158 +0,0 @@
# Tunnels
*The Prison-Architect dig: a disposed pawn goes down, not through — under the ground and everything
built on it, out past the last wall you were relying on.*
A locked door stops a prisoner who wants to walk out. It does nothing at all about a prisoner who
digs. This is the escape that ignores your perimeter, because it does not cross it — it goes beneath
it. It is slow, it is quiet, and it works for pawns who would never join a mood-driven riot.
## The crude pick
The dig needs a tool. The crude pick is filed off the cell's own furniture exactly the way a shiv is —
same disposition gate, same damage-to-furniture tell; see
[Improvised Weapons](Improvised-Weapons.md). Where the shiv is a weapon, this is a *way out*: it
carries no combat stats and is never equipped.
| Stat | Value |
|---|---|
| Description | *"Useless as a weapon and useless above ground — but pointed downward, patiently, it is a way out that no lock and no guard can see."* |
| Max HP | 60 |
| Mass | 1.2 kg |
| Concealability | **0.5** |
| Hides | in cell only (too bulky to ride on a body) |
| Deteriorates | yes |
Because it can only hide in the cell, a warden turning over the *room* can find the pick itself — and,
far more easily, the hole it is digging.
## A second secret riding on the first
A tunnel is *"the third thing a contraband item can be, after 'made' and 'used in a break': a thing
you dig your way OUT with, quietly, over days."* It is deliberately **not a job** you can catch a pawn
performing. There is no supervised task a warden could walk in on and interrupt — only a secret that
grows and a wall that eventually gives. The dig advances on the same 250-tick heartbeat that makes
contraband, so *the same search that finds a shiv can find the tunnel*.
The pick must first be **made** (or smuggled). Only once it is finished does the dig begin, as a
second, longer secret carried on the same hidden pick.
## Who digs
Digging gates on three things:
1. **A person, and held** — prisoner, slave, or ward patient.
2. **The disposition to dig for weeks:** a base chance of **0.08** — deliberately below the shiv's
0.10. *"Fewer pawns will dig for weeks than will palm a shiv."* It is a fixed fact about the pawn.
3. **A viable plan exists** — there has to be somewhere to surface (see below).
This is the entire reason tunnels live in Contraband and not in a prisoner-only escape mod:
> It works for prisoners **and ward patients** alike. Prisoner Realism's escapes are for "mood
> prisoners" mid-break bashing a door, and a committed ward patient is never that pawn. A patient with
> a filed-down pick and the disposition to use it can still, slowly, dig out — and nothing else in the
> ecosystem lets them.
## Planning the dig: aim for the wilderness
The target is **not** the cell wall. *"You do not go through the wall, you go under it."* The pawn
aims for the **nearest wilderness** — the first standable spot, scanning outward up to **60 tiles**,
that opens onto the map edge and is not the room they are held in.
Two consequences fall straight out of that:
- **Depth is your defence, and a single wall is not.** A tunnel from a deep bunker is a long dig; a
tunnel from a shack against the map edge is a short one. Wrapping one more wall around a cell does
almost nothing — the dig already ignores intervening walls entirely.
- **A fully enclosed, map-locked base with no reachable edge has nowhere to surface.** The plan fails,
no progress is made, and the tunnel **stalls** — progress is kept, not lost. Seal the map and the
shaft simply waits.
### How long
Dig time scales with how deep the cell sits — about **6 cells of depth per day**, clamped between 3
and 15 days, and jittered ±25% each poll:
| | Days |
|---|---|
| Minimum (shallow cell near the edge) | **3** |
| Maximum (deep bunker) | **15** |
| Per day of digging | ~6 cells of depth |
The floor of 3 days keeps even the shortest tunnel a *real threat window* you have time to catch; the
ceiling of 15 keeps the deepest from being effectively forever.
## The tell: spoil
A dig has to go somewhere, and the dirt is where you notice it. Each dig tick, about half the time,
the pawn drops one tile of dirt filth where they are digging:
> A dirt floor swallows it; a paved cell shows it — exactly where a player might notice.
It is cheap and occasional on purpose: enough that a paved cell slowly accumulates a suspicious mess,
not so much that it spams filth or litters a clean cell every tick. If you floor your cells, spoil is a
genuine visual cue that someone is digging.
## Finding a tunnel in a search
A tunnel is *"a second, far less hideable secret."* The pick hides at concealability 0.5, but the
**shaft** gives itself away in proportion to how far along it is. When a warden search reaches the
cell, an extra find chance is added on top of the tool's normal find chance — scaling up to **+0.40**
at a nearly-finished tunnel.
So a routine cell toss that finds a shiv can also catch a dig in progress — *"the same guard patrol
that finds a shiv finds the hole"* — and the deeper the shaft, the harder it is to miss. A foiled dig
counts against the prisoner the same as one that ran: on discovery, their escape-attempt tally ticks
up, which raises this pawn's future search priority sharply (a known tunneller is the prisoner a warden
checks first — see [Warden Search](Warden-Search.md)). The full find math is on the
[Warden Search](Warden-Search.md) page.
## Breakout
When the dig finishes:
1. **Re-plan the exit** so it is correct even if the base changed during the weeks of digging.
2. **Breach the outer wall or fence** the tunnel comes up beside — the *outermost* impassable wall or
fence between the cell and the surfacing point. It is destroyed, leaving a visible hole the colony
must repair, and proof of how they got out. An open perimeter needs no breach.
3. **Record the attempt** — it happened whether or not they get clear of the map.
4. **Surface beyond the perimeter.** They dug all the way out, so they emerge *outside*, not in the
yard, with a little spoil dirt to mark where they came up.
5. **Hand off to vanilla.** Now that they are loose and outside, the base game's prison-break flow —
and anything layered on it, e.g. **Prisoner Realism** — takes it from there. A pawn already outside
who no longer qualifies as an in-prison escapee simply flees on their own; the breach and the
emergence are the real outcome regardless.
The player gets one message: *"{pawn} has tunnelled out under the perimeter and escaped."* The tunnel
and the pick are spent together.
## How to defend against it
| Defence | Effect |
|---|---|
| **Floor the cells** | spoil dirt becomes visible; you can *see* a dig |
| **Search known offenders** | a logged escape attempt is the heaviest single term in search priority |
| **Deny the pick's raw material** | no workable furniture, no pick — same starve as the shiv |
| **Depth** | a deeper cell is a longer dig and a wider window to catch it |
| **Seal the map** | no reachable edge means the tunnel stalls indefinitely |
Note what does **not** help much: adding perimeter walls. The dig goes under them and only breaches the
*last* one on the way out.
## Quick reference
| Constant | Value | Meaning |
|---|---|---|
| Dig base chance | 0.08 | before nature × nurture; fixed per pawn |
| Wilderness search radius | 60 tiles | how far out it looks for a surfacing point |
| Cells per day | 6 | dig speed vs. cell depth |
| Min / max dig time | 3 / 15 days | clamps on depth ÷ 6 |
| Spoil chance per dig tick | 50% | one tile of dirt filth |
| Extra find chance | up to +0.40 | scales with how far along the dig is |
| Pick concealability | 0.5 | in cell only |
| On discovery / breakout | escape attempt logged | counted either way |
---
*Part of the **Institution** suite — Core · Contraband · Justice · Gangs, alongside Foul Play and
Ward. Each stands alone; together they interlock.*
Warden-Search.md
-181
@@ -1,181 +0,0 @@
# Warden Search
*The sixteenth warden job vanilla never wrote. A guard turns the cell over, and might find nothing —
which is exactly why it has to cost.*
The warden can chat, convert, feed, execute, enslave, release, suppress, and eleven other things.
Searching a prisoner is not one of them, and no such job exists anywhere in the base game. Contraband
adds it as a **new** warden job, not a change to an existing one, and builds it around a single hard
rule: **the search must be able to come up empty.**
## Authority vs. act
The design splits one job into two halves:
| Half | Question it answers | Notes |
|---|---|---|
| The search **assignment** | **Who** may be searched? | it is ordinary warden work — a warden already has the run of the prison, so no new authority is invented |
| The search **act** | **What** is a search? | walk to the pawn, turn them over, resolve |
> The assignment is the authority. The act is just the act.
Why bother splitting them? Because the enforcement layer is meant to grow. A future **Institution:
Police** module adds a *second* authority — a cop who may stop and frisk a **free colonist** — reusing
the same act with a **narrower reach** (a street frisk gets what is on the body, not what is under the
floorboards). That module is an *addition*, not a rewrite, precisely because "who may search" and
"what a search reaches" were never welded together.
## Who gets searched
The search is warden work, and it sits at a deliberate spot in the warden's priorities:
| Property | Value | Why |
|---|---|---|
| Work type | Warden | it is warden work |
| Priority within warden work | **below feeding** | a starving prisoner matters more than a hidden shiv |
| Capacities needed | Manipulation, Sight | you search with your hands and eyes |
| Ranked by suspicion | **yes** | pick the right prisoner, not the nearest |
That last one — ranking by suspicion rather than distance — is what lets a gnawed bed and a thick
record send the warden to the *right* prisoner first.
A search is offered only if all of these hold: the warden should be looking after this prisoner, the
per-prisoner cooldown is up, the prisoner is **awake, not downed, and not in a mental state**, and the
warden can reach them.
Note what is **not** checked:
> Whether the prisoner is actually hiding anything. **The warden does not know. Nobody knows until the
> cell is turned over.** If the job were only offered when there was something to find, the mere
> appearance of the job would BE the discovery, and searching would stop being a gamble the player
> pays for in warden-hours. An empty search has to be possible, and has to cost.
### The cooldown
The same prisoner cannot be turned over more than **once per day** (60,000 ticks). You cannot
brute-force a well-hidden shiv by re-searching the same prisoner ten times in an hour. Every search is
one shot, and then that prisoner is off the list for a day.
## Priority: the search reads the tells
Everyone is worth a routine toss; the tells push a prisoner up the queue. Priority is built up like
this:
- **Base 4** — a routine toss for every prisoner.
- **Up to +12 for a gnawed bed** — scaled by how damaged their owned bed is. A badly damaged bed
shoots to the top.
- **Up to +8 for their record** — prior catches (×2 each), contraband made in the past (×0.5 each),
and foiled escape attempts (×3 each, **the heaviest term**), capped at +8 so the record cannot
completely swamp fresh probable cause.
| Term | Weight | Meaning |
|---|---|---|
| Base | 4 | a routine toss for every prisoner |
| Gnawed bed | up to +12 | how far below full HP their owned bed sits |
| Times caught | ×2 | already caught with contraband before |
| Contraband made | ×0.5 | has finished contraband in the past |
| Escape attempts | ×3 | **the heaviest term** — a known tunneller is checked first, every time |
| (record cap) | +8 max | the record cannot completely swamp fresh probable cause |
The record is only read here, never created. The base of 4 for everyone is not an accident —
**innocent prisoners still get frisked**, because the search must be able to come up empty or its mere
offer would be the discovery.
**Worked example.** A prisoner whose bed sits at 40% HP (so 60% missing), with 2 prior catches and 1
foiled tunnel:
> 4 + (12 × 0.6) + min(8, 2×2 + 1×3) = 4 + 7.2 + 7 = **18.2**
versus **4** for a clean prisoner with an intact bed. The warden walks past the quiet one and goes
straight for the one who has been busy. This closes the loop
[Improvised Weapons](Improvised-Weapons.md) opens: whittling a shiv chews the bed, the damage is
probable cause, and the warden's *suspicion* — not the player's eye — sends them to search.
## The act: what a search does
The searcher walks to the subject, spends a **900-tick** turn with a progress bar, then resolves.
Resolution always does two things, hit or miss:
1. Starts the daily cooldown on that prisoner.
2. Ticks up how many times this pawn has been searched — *"classification and the guard's future
suspicion read how often this pawn has been turned over."*
Then it goes through everything the subject is hiding that this search can **reach** (a full warden
search reaches both the body and the cell; a narrower future street-frisk reaches only the body). If
nothing is reachable, the job ends here — the time was still spent, and the player is told nothing.
### Find math, per hidden item
For each reachable secret, the chance to find it is built like this:
- Start from a **base of 0.35**, plus **0.03 for each level of the warden's Social skill**.
- Scale by how concealable the item is: the factor pivots at concealability 0.5. A drug at 0.5 is
average (×1.0), a shiv at 0.75 is halved (×0.5), a heavy weapon at 0.35 is boosted (×1.3).
- If the item is a **tunnel in progress**, add its extra find chance (up to +0.40 for a nearly
finished shaft), and the ceiling rises.
- Multiply the whole thing by the warden's **Diligence** — a lax, kind, or miserable guard scales it
down.
- Before the find roll, a **bent** warden gets a flat chance to look the other way (their Corruption ×
0.6) even on an item they would otherwise have found.
- The chance is clamped to between 0.02 and 0.95 (0.98 for a tunnel).
Reading it in plain terms:
- **Skill raises the ceiling; concealability lowers it.** Each level of the warden's Social skill adds
a little; a well-hidden item takes a lot of it back.
- **A good warden still misses a well-hidden shiv more often than not.** A level-8 Social warden
searching for a 0.75-concealability shiv is already well under a coin-flip *before* Diligence scales
it down further.
- **A tunnel is a different story.** The pick hides at 0.5, but a nearly-finished shaft adds up to
+0.40 and the cap rises to 0.98 — the deeper the dig, the harder it is to miss. A routine cell toss
catches a dig in progress.
- **The warden's own thoroughness and price** enter last: Diligence multiplies the whole chance down
for a lax, kind, or miserable guard, and Corruption gives a bent guard a flat chance to look the
other way even on an item they would otherwise have found. Both are on the
[Corruption](Corruption.md) page.
### On a find
- The item is confiscated — it **never becomes a real object**, nothing drops on the floor.
- The prisoner's times-caught tally ticks up (raising future suspicion, feeding classification).
- If it was a tunnel, their escape-attempt tally ticks up too — a foiled dig counts the same as one
that ran.
The player gets a message — *"{warden} searched {prisoner} and found hidden {item}"*, or the tunnel
variant. If nothing is found the player is told **nothing**: they do not learn there *was* something,
only that the warden's time was spent.
## Writing back to the record
Every outcome updates Core's criminal record, which is what makes the search a *loop* rather than a
one-off dice roll:
| Tally | Updated when | Read by |
|---|---|---|
| Times searched | every search, hit or miss | priority, suspicion, classification |
| Times caught | a find | priority (×2), classification |
| Escape attempts | a foiled tunnel | priority (×3, heaviest), classification |
If you run **Institution: Justice**, those same tallies drive a prisoner's security classification and
feed the deterrence signal — a prison that catches contraband becomes a prison that classifies its
troublemakers correctly and deters the next attempt. If you run Contraband alone, the tallies still
route the warden. See [Compatibility](Compatibility.md).
## Quick reference
| Constant | Value | Meaning |
|---|---|---|
| Base find chance | 0.35 | before skill and concealability |
| Per Social level | +0.03 | skill raises the ceiling |
| Find chance clamp | 0.02 .. 0.95 | (0.98 for a tunnel) |
| Search duration | 900 ticks | one turn, hit or miss |
| Search cooldown | 60,000 ticks (1 day) | per prisoner |
| Priority base | 4 | every prisoner is worth a routine toss |
| Gnawed-bed weight | up to +12 | how far below full HP their bed sits |
| Record weight | up to +8 | caught ×2 + made ×0.5 + escapes ×3 |
| Default reach | body + cell | narrowed by a future street-frisk |
---
*Part of the **Institution** suite — Core · Contraband · Justice · Gangs, alongside Foul Play and
Ward. Each stands alone; together they interlock.*