institution/Wiki/contraband/Tunnels.md

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. CB_DiggingTool is a crude pick, filed off the cell's own furniture exactly the way a shiv is (AcquireWorker_Improvise — same disposition gate, same damage-to-furniture tell; see Improvised Weapons). 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
hideIn	InCell only (too bulky to ride on a body)
acquireWorker	AcquireWorker_Improvise
escapeWorker	EscapeTunnelWorker
Deterioration	2.0

Because it hides InCell only, 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. There is no supervised task a warden could walk in on and interrupt — only a secret that grows and a wall that eventually gives. Progress is driven from MapComponent_Contraband's poll (TickTunnels), 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 (Ready) does the dig begin, as a second, longer secret carried on the same ConcealedItem (escapeProgress, escapeWall).

Who digs

EscapeTunnelWorker.WouldDig gates on three things:

1. Humanlike and held — prisoner, slave, or ward patient (IsHeld, via Core's secured context).

2. The disposition to dig for weeks:

   Propensity.Would(holder, 0.08, SaltTunnel)
   

   Base chance 0.08 — deliberately below the shiv's 0.10. "Fewer pawns will dig for weeks than will palm a shiv." Seeded per pawn, so it is a fixed fact about them.

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." TryPlan finds the nearest wilderness — the first standable cell, scanning radially outward from the holder up to 60 tiles (MaxSearchRadius), whose room touches 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. TryPlan fails, ProgressPerCheck returns 0, 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:

requiredDays = clamp(distanceToWilderness / 6, 3, 15)      // CellsPerDay = 6
progressPerPoll = 250 / (requiredDays × 60000)  ×  Rand.Range(0.75, 1.25)

	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, with a 50% seeded chance (OnDigTick), the worker drops one tile of Filth_Dirt at the holder's position:

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 has concealability 0.5, but the shaft gives itself away in proportion to how far along it is. When a warden search reaches the InCell site, ExtraDiscoverChance is added on top of the tool's normal find chance:

extraChance = clamp01(escapeProgress) × 0.4      // 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 is logged the same as one that ran: on discovery, CriminalRecord.escapeAttempts is incremented, which raises this pawn's future search priority sharply (a known tunneller is the prisoner a warden checks first — see Warden Search). The full find math is on the Warden Search page.

Breakout

When escapeProgress reaches 1, OnBreakout fires:

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 (LastContainmentOnLine — the outermost impassable edifice or fence between the cell and the surfacing point, walking inward from the exit). It is destroyed with KillFinalize — a visible hole the colony must repair, and proof of how they got out. An open perimeter needs no breach.
3. Record the attempt (escapeAttempts++) — 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: the pawn is teleported to the exit cell, with a little spoil dirt to mark where they came up.
5. Hand off to vanilla (PrisonBreakUtility.StartPrisonBreak). 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 — the ConcealedItem is removed.

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; seeded 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 distance / 6
Spoil chance per dig tick	50%	one tile of Filth_Dirt
Extra find chance	up to +0.40	scales with escapeProgress
Pick concealability	0.5	InCell only
On discovery / breakout	escapeAttempts++	logged either way

---

Part of the Institution suite — Core · Contraband · Justice · Gangs, alongside Foul Play and Ward. Each stands alone; together they interlock. Developed with substantial assistance from Claude (Anthropic).