diff --git a/Compatibility.md b/Compatibility.md new file mode 100644 index 0000000..76ba42f --- /dev/null +++ b/Compatibility.md @@ -0,0 +1,116 @@ +# 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.* diff --git a/Concealment-and-Intake.md b/Concealment-and-Intake.md new file mode 100644 index 0000000..00600fb --- /dev/null +++ b/Concealment-and-Intake.md @@ -0,0 +1,201 @@ +# 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.* diff --git a/Corruption.md b/Corruption.md new file mode 100644 index 0000000..5f48ce9 --- /dev/null +++ b/Corruption.md @@ -0,0 +1,111 @@ +# 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.* diff --git a/Criminal-Record.md b/Criminal-Record.md deleted file mode 100644 index 6263798..0000000 --- a/Criminal-Record.md +++ /dev/null @@ -1,102 +0,0 @@ -# Criminal Record — the history of fact - -If [Propensity](Propensity.md) is *suspicion* — "this pawn seems dangerous" — the criminal record is -*fact*: "this pawn **has** escaped twice and shanked a guard." The two are deliberately different -kinds of thing. Propensity is computed fresh from who a pawn is and how they're treated; a record is a -durable log of what they've actually done, written once when it happens and read forever after. - -There is exactly **one criminal record per pawn**, and the whole suite shares it. Classification grades -on it, parole gates on it, the deterrence loop reacts to it, and reintegration remembers it. Because -everyone reads the same record, no two parts of the suite can disagree about a pawn's past. - ---- - -## What a record remembers - -A record is a small set of counters plus two special marks. Core provides the record and keeps it -safe; the individual events are logged by whichever mod they happen in. - -| What it tracks | Starts at | Meaning | Tracked by | Used by | -|---|---:|---|---|---| -| Crimes committed | 0 | count of committed crimes | Justice (and gang fights) | classification risk score, deterrence | -| Escape attempts | 0 | breakout attempts | Contraband | classification risk score | -| Contraband made | 0 | items brewed / whittled | Contraband | classification risk score | -| Times searched | 0 | how often searched | Contraband (warden search) | search prioritisation | -| Times caught | 0 | searches that found something | Contraband (warden search) | classification risk score | -| Last crime | never | when the most recent crime happened | Justice | recency / cooldown checks | -| Reform | 0 | rehabilitation score (see below) | Justice (discipline, parole) | **Propensity's Nurture**, parole gate, reintegration | -| Pardoned | no | granted a clean slate after genuine reform | Justice (on release) | parole gate, reintegration | - -"Last crime" starts at *never* — a distinct value from "at the very first moment of the game." -Everything else starts at zero / no. - -> **Who logs what.** Core is the *vault*, not the *clerk*. It hands out records and keeps them; the -> actual "a crime just happened, add one" logging lives in the mod where the event occurs. The columns -> above name which mod does that — Core itself only holds the fields. - -## Reform — the pivot of the suite - -Most of a record is inert tallies. **Reform** is the one entry that feeds back into behaviour, and it's -worth its own section. It's raised by good treatment and good conduct, decays without either, and can -be driven negative by harsh punishment. A record is where a sentence's *outcome* is stored, and three -systems lean on that one number: - -- **[Propensity](Propensity.md)'s Nurture** scales a pawn's disposition by their reform score — so a - genuinely rehabilitated pawn (reform above 0) is calmer *for good*, and a prisonized one (reform - below 0) is inflamed *for good*. This is how institutionalization and recidivism enter the game - without a separate mechanic bolted on. -- **Parole** (Justice) gates release on it: a pawn is only releasable once reform clears a threshold. - It's the number that says "this one is ready." -- **Reintegration** reads it to decide when a clean slate is earned — which is what the *pardoned* - mark records. - -The negative range isn't a bug — it's the "hardened" end of the spectrum, and Nurture is written to -expect it. - -## Pardoned and blank records - -The **pardoned** mark flips on exactly once, after genuine reform, so reintegration can grant a clean -slate without erasing the history that earned it — the counters stay, but the pawn is marked forgiven. - -A record counts as **blank** when nothing meaningful has ever been written to it: no crimes, no escape -attempts, no contraband, never caught, reform still 0, not pardoned. Note what blankness *ignores*: -times searched and the last-crime time aren't part of the test. A pawn who was searched and found clean -— searched but never caught, never a crime — still counts as blank. That's intentional: being -*checked* is not a mark against you, only being *found* is. - ---- - -## Records are created only when needed - -Records are made lazily. A pawn only gets a record the first time something is actually **written** to -it — a crime, a search that found something, a reform change. Simply **reading** a pawn's disposition -never creates one. - -That distinction matters because Propensity's Nurture reads a pawn's reform score constantly, on every -pawn on the map, as part of judging their mood. If merely checking disposition created a record, every -mood check would stamp a criminal file onto every innocent pawn on the map. Because reading only peeks -— and tolerates a pawn having no record at all — the innocent stay off the books. - -The rule the whole suite follows: **something happened → a record is created and written; just looking -→ no record is created.** - ---- - -## Persistence - -Records save with your game and reload with it, and there's exactly one shared store for the whole -colony — no mod keeps its own private copy, which is what keeps them all agreeing with each other. - -On load, that store cleans itself up. Three kinds of record get dropped: - -1. **Records of pawns who are gone** — dead or removed. They take their records with them. -2. **Corrupt entries** — a guard against a broken save. -3. **Blank records** — anything still blank. There's no reason to keep a file that records nothing. - -The upshot: **records are cheap and self-cleaning.** Anything that never got a real mark written to it -simply evaporates on the next load, so the save never bloats with one empty file per pawn ever glanced -at. - ---- - -*Part of the **Institution** suite.* diff --git a/Home.md b/Home.md index f83b12e..757ea93 100644 --- a/Home.md +++ b/Home.md @@ -1,88 +1,126 @@ -# Institution: Core — Wiki +# Institution: Contraband -*The shared foundation of the **Institution** suite: a set of RimWorld 1.6 mods about what an -institution does to the people inside it, and the crime, policing, and justice that put them there.* +*Prisoners get hold of things they should not have. Wardens turn the cell over looking for them.* -Core is the engine every other Institution mod runs on. **On its own it changes nothing you can -see** — no items, no jobs, no new menus. It sits completely quiet until another Institution mod is -installed on top of it. You install Core only because something else asks for it. +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. -This wiki explains what that hidden engine actually does once a mod above it puts it to work — down to -the exact numbers, because knowing how the numbers move is half the fun of running a prison. - ---- +> **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. ## 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.** -That single sentence is the whole suite. Colonists, prisoners, and slaves drift toward crime on a -continuous spectrum; a policing and justice layer discovers, catches, punishes, reforms, or paroles -them. Core is where the *spectrum* itself lives — before anyone is caught, before there is a record to -read, before there is a warden to search them. +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. -## Why a shared engine +## Vanilla built the demand and forgot the supply chain -The propensity idea didn't start out abstract. It grew up twice, in two different mods: one deciding -which drunk, miserable pawn starts a mess, and one deciding which prisoner whittles a shiv the moment a -door opens. Both were asking the same real question — *would **this** pawn do it?* — and each answered -it its own way, which meant they could disagree about who was dangerous. +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. -Core exists so they stop disagreeing. When the contraband system, the justice system, and the gang -system all read one disposition engine, they agree about who is dangerous instead of each judging it -separately and drifting apart. The pawn who is "the scary one" is the scary one to every part of the -suite at once. That coherence — not any single number — is the point of a shared foundation. +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. -Core carries exactly the three things every Institution mod needs and none should own alone, and -nothing else: +What does **not** exist is any answer to two questions: -| Pillar | Answers | Page | +| 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 | |---|---|---| -| **Propensity** | *Would this pawn do it?* (nature × nurture) | [Propensity](Propensity.md) | -| **Criminal record** | *What has this pawn actually done?* (one history per pawn) | [Criminal Record](Criminal-Record.md) | -| **Secured context** | *What kind of hold is this pawn under, and who may search them?* | [Secured Context](Secured-Context.md) | +| **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) | -The distinction between the first two is the spine of the whole design: **propensity is suspicion, a -record is fact.** Propensity says "this pawn *seems* dangerous"; a record says "this pawn *has* -escaped twice and shanked a guard." Keeping them separate is what lets the colony act on evidence -instead of on vibes. +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)**. -## The pages of this wiki +## How everything is contraband without a list -- **[Propensity](Propensity.md)** — nature × nurture in full: the trait-weight table, the nurture - multiplier ladder, the disposition formula with worked examples, and why each pawn's roll is fixed - rather than re-rolled. -- **[Criminal Record](Criminal-Record.md)** — everything a record remembers, who fills in each part, - how it persists across saves, and why *reform* is the pivot of the whole suite. -- **[Secured Context](Secured-Context.md)** — the Free / Prisoner / Slave kinds, what counts as - "held" versus what counts as "able to hide something," and why the suite keys off this instead of - "is a prisoner." -- **[Treatment Engine](Treatment-Engine.md)** — the shared rehabilitation maths: mark a condition - treatable, reduce it a little each session by skill and facility quality, and build a recovery track - toward discharge. Ward's psychiatric care and Justice's reform run on this one engine. -- **[Modder API](Modder-API.md)** — the "for modders" page: the tools any mod can call to build on - Core. Players can skip it. +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. Core sits underneath everything -else. +Each mod stands alone as an install; together they form one system. -| Mod | What it adds | Needs | +| Mod | Owns | Depends on | |---|---|---| -| **Institution: Core** (this) | the propensity / record / context engine | base game only | -| **Institution: Contraband** | concealment, improvised shivs, tunnels, warden search, warden corruption | Core | -| **Institution: Justice** | classification, deterrence, discipline, parole, regime, and **policing** (colony crime → weighed arrest) | Core, Harmony | -| **Institution: Gangs** | gangs as contraband economies: joining, smuggling, rivalry, fights-as-crime | Core, Contraband, Justice | -| **Institution: Ward** | psychiatric care — a prisoner treated, not punished, on Core's treatment engine | Core, Harmony | -| **Foul Play** | the vessel + substance + throw framework, home of the "Piss Nuke" | standalone; bridges to Core + Contraband | - -## Requirements & load order - -- **RimWorld 1.6.** Core needs only the base game — no Harmony, no DLC, no other mod. -- Load Core **before** any other Institution mod in your mod list. +| **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 | — | --- -*Part of the **Institution** suite.* +*Part of the **Institution** suite — Core · Contraband · Justice · Gangs, alongside Foul Play and +Ward. Each stands alone; together they interlock.* diff --git a/Improvised-Weapons.md b/Improvised-Weapons.md new file mode 100644 index 0000000..6fb1820 --- /dev/null +++ b/Improvised-Weapons.md @@ -0,0 +1,176 @@ +# 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.* diff --git a/Modder-API.md b/Modder-API.md deleted file mode 100644 index 402ea03..0000000 --- a/Modder-API.md +++ /dev/null @@ -1,238 +0,0 @@ -# Modder API — building on Core - -Core is a library. It has no XML, no defs, no UI — its entire purpose is to be *called*, by the other -Institution mods and by yours. This page is the public surface, with the one seam that matters most -(`Propensity.DeterrenceFactor`) explained in full. - -> **This page is for modders.** Every other page in this wiki is written for players; this one is the -> technical surface for building on Core. If you just want to know how the mod plays, start at the -> [Home](Home.md) page and the [Propensity](Propensity.md) / [Criminal Record](Criminal-Record.md) / -> [Secured Context](Secured-Context.md) / [Treatment Engine](Treatment-Engine.md) pages instead. - -Everything here is verified against the three source files in `Source/Core/`. - ---- - -## The namespace is `Contraband` - -Before anything else: **all of Core's types live in `namespace Contraband`**, not `Core` and not -`Institution`. This is historical — the engine was extracted from Institution: Contraband — and it is -not going to change under you, but it does mean your `using` looks slightly surprising: - -```csharp -using Contraband; // Propensity, CriminalRecord, GameComponent_CriminalRecords, - // SecuredKind, SecuredContext, SecuredContexts, - // TreatmentProgram, TreatableConditionExtension -``` - -Reference the assembly `InstitutionCore.dll` (packageId `flan.institution.core`) and load your mod -after Core. - -## The public surface at a glance - -| Call | Returns | Creates state? | Use for | -|---|---|---|---| -| `Propensity.Nature(pawn)` | `float 0..1` | no | fixed trait-based disposition | -| `Propensity.Nurture(pawn)` | `float` (multiplier) | no | live circumstance multiplier | -| `Propensity.Would(pawn, baseChance, salt, cap=0.85)` | `bool` | no | the seeded yes/no for a behaviour | -| `Propensity.DeterrenceFactor` | `Func` field | — | the seam a justice layer fills | -| `GameComponent_CriminalRecords.For(pawn)` | `CriminalRecord` | **yes** (blank on first ask) | write paths | -| `GameComponent_CriminalRecords.PeekFor(pawn)` | `CriminalRecord?` | no | read paths | -| `SecuredContexts.Of(pawn)` | `SecuredContext?` | no | one pawn's hold kind | -| `SecuredContexts.OnMap(map)` | `IEnumerable` | no | every held/free pawn on a map | -| `TreatmentProgram.HasTreatableCondition(pawn)` | `bool` | no | is there a marked condition to work through? | -| `TreatmentProgram.ReduceConditions(pawn, strength)` | `void` | mutates hediffs | run one session's worth of treatment | -| `TreatmentProgram.FacilityQuality(pawn)` | `float 0.5..1.5` | no | scale a session by the room's quality | -| `TreatmentProgram.AdvanceRecovery(pawn, def, amount)` | `float` | **yes** (recovery hediff) | build a discharge / parole track | - -All of these are `static` and null-safe. None throws on a null pawn; they return `0.05`/`1f`/`null`/ -`false` as appropriate. See the [Propensity](Propensity.md), [Criminal Record](Criminal-Record.md), -and [Secured Context](Secured-Context.md) pages for the mechanics behind each. - ---- - -## Asking "would this pawn?" - -The idiomatic pattern for a new behaviour is: pick a **base rate**, pick a **stable salt** unique to -your question, and call `Would`. Do not re-implement the nature/nurture math — that is the whole point -of the shared engine. - -```csharp -using Contraband; - -// A unique, STABLE salt for this specific question. Any constant int works; keep it -// distinct from other questions so the rolls stay independent per behaviour. -private const int Salt_WouldStealMeds = 0x5EED01; - -if (Propensity.Would(pawn, baseChance: 0.08f, salt: Salt_WouldStealMeds)) -{ - // this pawn, under these conditions, is the kind who does this -} -``` - -Because the roll is seeded on `pawn.thingIDNumber ^ salt`, the answer is a stable fact per pawn per -question and survives save/reload — so you can ask it repeatedly and get a consistent character, and -different salts give you independent facts about the same pawn. Pass a custom `cap` if `0.85` is the -wrong ceiling for your behaviour (e.g. a lower cap for something that should always keep a large -chance of not happening). - -If you only need the ingredients — say, to display a disposition readout or gate a threshold — read -`Nature` and `Nurture` directly. Institution: Gangs, for instance, joins a pawn to a gang when -`Nature(pawn) * Nurture(pawn)` clears its own threshold, computed from these two calls rather than -from `Would`. - -## Reading and writing records - -Follow the one rule from the [Criminal Record](Criminal-Record.md) page — **write with `For`, read -with `PeekFor`** — so read paths never litter the save with blank records. - -```csharp -using Contraband; - -// WRITE: an event happened, so we need a record to write to. -CriminalRecord rec = GameComponent_CriminalRecords.For(pawn); -rec.contrabandMade++; - -// READ: peek, and tolerate null (the pawn may have no record yet). -CriminalRecord existing = GameComponent_CriminalRecords.PeekFor(pawn); -if (existing != null && existing.reform < 0f) -{ - // this pawn has been hardened -} -``` - -Core owns the storage and persistence; you own the meaning of your own events. Do not keep your own -per-pawn crime dictionary — that is exactly the fragmentation Core exists to prevent. - -## Working across hold kinds - -Reduce a pawn to its context and branch on the *predicate*, not the label: - -```csharp -using Contraband; - -SecuredContext? maybe = SecuredContexts.Of(pawn); -if (maybe is SecuredContext ctx && ctx.IsHeld) -{ - // prisoner OR slave OR ward patient -- all covered, no special cases -} - -// Sweep everyone the suite cares about on a map: -foreach (SecuredContext c in SecuredContexts.OnMap(map)) -{ - if (c.CanConceal) { /* consider hoarders too, not just the held */ } -} -``` - -`Of` returns `null` for anything the suite does not model (animals, mechs, the dead), so a `null` -check is your "not our business" branch. - -## Running a treatment programme - -Core carries the maths of "sustained attention in a secured facility reduces a marked condition and -builds a recovery track toward discharge" — the shared engine behind Ward's psychiatric care and -Justice's rehabilitation. Mark a hediff treatable with `TreatableConditionExtension`, then drive it -from your own job or interaction: - -```csharp -using Contraband; - -float strength = skill * TreatmentProgram.FacilityQuality(pawn) * share; // your own blend -TreatmentProgram.ReduceConditions(pawn, strength); // lower the condition -if (!TreatmentProgram.HasTreatableCondition(pawn)) -{ - TreatmentProgram.AdvanceRecovery(pawn, MyDefOf.Recovery, 0.15f * strength); // build discharge -} -``` - -You own the interaction mode, the job, the recovery hediff (give it a negative `severityPerDay` so it -decays without attention), and the discharge alert; Core owns only the numbers. Full formulas and the -consumer contract are on the **[Treatment Engine](Treatment-Engine.md)** page. - ---- - -## The `DeterrenceFactor` seam - -This is the most important extension point in Core, and the reason Core can remain a **dependency-free -leaf** while a colony-wide deterrence feedback loop runs *through* it. - -### What it is - -```csharp -// In Propensity: -public static System.Func DeterrenceFactor = _ => 1f; -``` - -A single static delegate. `Nurture` multiplies its result by `DeterrenceFactor(pawn)` as its last -step. Out of the box the delegate returns `1f` for every pawn — perfectly neutral — so **Core alone -behaves as if deterrence did not exist.** - -### What it is *for* - -Deterrence is a property of the whole colony's climate of order: a well-policed colony should deter -everyone a little; a lawless one should embolden them. That is a feedback loop — catching and -punishing *one* pawn changes the disposition of *the rest*. But deterrence itself is a justice-layer -concept, and Core must not know the justice layer exists. - -The seam resolves the tension. Core defines *where* the colony's climate multiplies into disposition -(the last line of `Nurture`) without defining *what* that climate is. From the source: - -> *"Deterrence lives in the Justice layer, so Core reads it through the seam above — neutral until -> Justice fills it. This one seam is what keeps Core a dependency-free leaf despite the deterrence -> feedback loop running through it."* - -### How Institution: Justice fills it - -When Institution: Justice loads, it assigns the delegate, pointing it at its own live deterrence -level. The shape it installs maps a `0..1` deterrence reading to a multiplier that straddles `1.0`: - -```csharp -// Illustrative — this lives in Institution: Justice, not Core. -Propensity.DeterrenceFactor = pawn => -{ - float level = DeterrenceLevelFor(pawn.Map); // 0 = lawless, 1 = tightly policed - return Mathf.Lerp(1.3f, 0.7f, level); // lawless emboldens, order deters; neutral at 0.5 -}; -``` - -| Deterrence level | Factor | Effect on disposition | -|---|---:|---| -| `0.0` (lawless) | `1.3` | everyone ~30% more inclined | -| `0.5` (baseline) | `1.0` | neutral — a default colony sits exactly here | -| `1.0` (tightly policed) | `0.7` | everyone ~30% less inclined | - -*(The `1.3 → 0.7` range, neutral at the `0.5` baseline, are Justice's numbers, documented here for context; -Core only guarantees the neutral `1f` default. Confirm against Institution: Justice's own source for -its current values.)* - -### How to fill it yourself - -If you are writing your own policing or morale layer and want it to feed disposition the same way, -just assign the delegate — ideally at game load, and ideally composing with whatever is already there -rather than clobbering it: - -```csharp -using Contraband; -using UnityEngine; - -// Compose: fold your factor into any existing one (e.g. Justice's) instead of overwriting. -var previous = Propensity.DeterrenceFactor; -Propensity.DeterrenceFactor = pawn => previous(pawn) * MyClimateFactorFor(pawn); -``` - -Two cautions. First, it is a single static field — if two mods both *assign* it (rather than compose), -the last one wins, so compose when you can. Second, keep your factor bounded and centred near `1.0`: -`Nurture` has no clamp on this term, so an extreme factor multiplies straight through into every -pawn's `Would` roll. Return `1f` when you have nothing to say, exactly as the default does. - -### Why a delegate and not a dependency - -The alternative — Core calling into Justice — would make Core depend on Justice, inverting the whole -topology and breaking Core's promise that it references *only the base game*. A single assignable -`Func`, neutral by default, lets the feedback loop run through Core while the arrow of -dependency still points only *at* Core. It is the smallest possible seam that buys the largest possible -decoupling, and it is why Core can sit at the bottom of the suite with zero dependencies of its own. - ---- - -*Part of the **Institution** suite.* diff --git a/Propensity.md b/Propensity.md deleted file mode 100644 index f95a418..0000000 --- a/Propensity.md +++ /dev/null @@ -1,212 +0,0 @@ -# Propensity — nature × nurture - -Propensity is the suite's disposition engine. It answers one question and only one: *"would **this** -pawn do it?"* — never *"would a prisoner,"* never *"would a colonist."* Every behaviour in the suite -that hinges on a pawn's character comes back to this, so crime, contraband brewing, escape arming, and -gang recruitment all read the same answer instead of each guessing. - -The model is deliberately old-fashioned: **nature × nurture.** - -- **Nature** is a fixed property of the person — their traits. Almost nobody is strongly disposed, and - this never changes over a pawn's life. -- **Nurture** is what the colony has done *to* them — mood, mistreatment, unmet needs, the shadow a - sentence leaves. This is the half **you** control, and the half no other mod models. - -Good conditions pull nurture down; neglect and cruelty push it up. A saint left to rot can cross the -line; a monster kept content and deterred may never act. Both of those stories are possible by design. - ---- - -## Nature — who they are - -Every pawn starts from a **baseline of 0.05** — the floor of the human condition in this model: -everyone is capable of *something*, most people barely. From there, each trait the pawn has adds or -subtracts, and the total is held to the 0–1 range (never below 0, never above 1). - -### Trait weights - -Traits are matched **by name**, so if a trait's mod isn't installed that entry is simply skipped. -That's how Core uses Vanilla Traits Expanded's dark traits when VTE is present without *requiring* VTE -to be installed. - -| Trait | Weight | Source | Note | -|---|---:|---|---| -| Psychopath | **+0.45** | Vanilla | no empathy; the heaviest single input | -| Kleptomaniac | **+0.40** | Vanilla Traits Expanded | counted if VTE is installed | -| Bloodlust | **+0.35** | Vanilla | enjoys violence | -| Pyromaniac | **+0.30** | Vanilla Traits Expanded | counted if VTE is installed | -| Greedy | **+0.25** | Vanilla | wants more than their share | -| Abrasive | **+0.15** | Vanilla | friction with everyone | -| Ascetic | **−0.15** | Vanilla | wants little, takes little | -| Kind | **−0.30** | Vanilla | the strongest pull *down* | - -Core adds no traits of its own — it reads the ones the game and your other mods already provide. -Vanilla's own dark traits count right alongside VTE's. - -### Worked Nature values - -Because weights simply add and then clamp, Nature is easy to read by hand: - -| Pawn | Arithmetic | Nature | -|---|---|---:| -| Ordinary pawn (none of the above) | 0.05 | **0.05** | -| Kind pawn | 0.05 − 0.30 = −0.25 → clamp | **0.00** | -| A single Greedy trait | 0.05 + 0.25 | **0.30** | -| Psychopath | 0.05 + 0.45 | **0.50** | -| Psychopath **and** Kind | 0.05 + 0.45 − 0.30 | **0.20** | -| Greedy + Abrasive | 0.05 + 0.25 + 0.15 | **0.45** | -| Psychopath + Bloodlust + Kleptomaniac | 0.05 + 0.45 + 0.35 + 0.40 = 1.25 → clamp | **1.00** | - -Two things fall out of this. First, the clamp isn't decorative: a Kind pawn floors at exactly `0` -(nature can never make them *disposed*, only never disposed), and a stacked monster ceilings at `1`. -Second, traits genuinely net against each other — a Kind Psychopath is a real, middling `0.20`, not a -contradiction. - -Most rolled pawns sit at or near the `0.05` floor. That's intended: a colony full of ordinary people -is supposed to be mostly safe on nature alone. What makes them dangerous is nurture. - ---- - -## Nurture — what you have done to them - -Nurture is a **multiplier**. An ordinary pawn under ordinary conditions sits at **1.0**. The number -rises as things go wrong and falls as they go right. Each lever below stacks on top of the last. - -### The multiplier ladder - -| Lever | Factor | Applies when | Stacks? | -|---|---|---|---| -| **Despair** | ×2.5 | mood below 20% | mutually exclusive with "badly kept" | -| **Badly kept** | ×1.6 | mood 20–35% | mutually exclusive with "despair" | -| **Held & unhappy** | ×1.4 | held **and** mood below 40% | on top of the mood lever | -| **Prisonization** | × (depends on reform, see below) | the pawn has a non-zero reform score | on top | -| **Deterrence** | × (the colony's climate of order) | always (neutral 1.0 with only Core) | on top | - -The two mood levers are either/or: a pawn is either in despair *or* badly kept, never both. "Held & -unhappy" is separate and multiplies again — so a mistreated prisoner in despair compounds -`2.5 × 1.4 = 3.5` before anything else. That is a badly run cell. - -### Prisonization — the reform lever - -The reform lever is where a sentence leaves a permanent mark. A pawn's **reform score** runs from -about −1 to +1 and turns into a multiplier: - -| Reform score | Meaning | Factor | -|---:|---|---:| -| **+1.0** | fully rehabilitated | 0.50 | -| +0.5 | improving | 0.75 | -| 0 | untouched (no effect) | *1.00* | -| −0.5 | hardening | 1.25 | -| **−1.0** | prisonized | 1.50 | -| beyond +1.2 | (over-reformed) | floors at **0.40** | -| beyond −2.0 | (utterly broken) | ceilings at **2.00** | - -Reform is nominally a 0-to-1 rehabilitation score, but harsh punishment can drive it **negative** — -that's the "hardened, prisonized" end. Within the realistic −1…+1 range the factor spans 0.5…1.5; the -0.4 / 2.0 limits only bite at the extremes, catching a pawn who's been endlessly punished or endlessly -rehabilitated. - -Propensity only *reads* this score — nothing in Core moves it. The Justice layer's discipline and -parole are what nudge it up or down, which is how institutionalization and recidivism enter the game -without a separate mechanic. A pawn broken by a brutal prison stays broken (nurture ×1.5) after -release; a pawn genuinely reformed stays calmer (×0.5) for good. The scar rides on one number. - -### Deterrence — the climate of order - -The final lever multiplies by the colony's overall **climate of order**. **With only Core installed -it's neutral — a flat 1.0** — because Core by itself doesn't know what deterrence is. Install -**Institution: Justice** and it fills this in: a well-policed colony pulls the factor below 1 and -deters everyone a little; a lawless one pushes it above 1 and emboldens them. That's what makes -catching and punishing *one* pawn matter to the disposition of *the rest*. - -With only Core installed, this lever does nothing, and that is correct. The technical details of how a -mod fills in deterrence are on the [Modder API](Modder-API.md) page. - ---- - -## Would — the full roll - -Nature and Nurture are ingredients. The full roll is the meal: the actual yes/no for a specific -behaviour at a specific base rate. For a given behaviour, the chance works out to: - -> **chance = base rate × (0.1 + Nature × 2) × Nurture**, capped at 85%. - -Three things are happening there: - -1. **Base rate** is the behaviour's own dial — how likely an *average* pawn is to do this particular - thing (a rare act uses a small number, a common one a larger). Core doesn't decide it; whichever - system is asking does. -2. **(0.1 + Nature × 2)** is the nature amplifier. It spans **×0.1** (a saint, Nature 0) to **×2.1** - (Nature 1). At the common `0.05` floor it's **×0.2** — so an ordinary pawn is one-fifth as likely - as the base rate, while a maxed monster is over twice as likely — *before* nurture. -3. **× Nurture** applies circumstance on top, and the whole thing is capped at **85%** by default. - Nobody is ever a dead certainty; there's always slack. A behaviour that wants a harder or softer - ceiling can set its own cap. - -### Worked example 1 — an ordinary colonist, content - -Base rate 10%, an ordinary pawn (Nature 0.05), good mood so Nurture 1.0: - -- nature term = 0.1 + 0.05 × 2 = 0.2 -- chance = 0.10 × 0.2 × 1.0 = 0.02 → **2%** - -Two percent — and, critically, **fixed**. For this pawn and this question it's a settled 2% coin that -either comes up or doesn't; it isn't re-flipped every moment. - -### Worked example 2 — a mistreated psychopath prisoner - -A Psychopath + Bloodlust prisoner (Nature 0.85), mood 15% (despair ×2.5), held and unhappy (×1.4), -reform −0.5 (hardening → ×1.25), Core-only so deterrence 1.0. Base rate 10%: - -- nature term = 0.1 + 0.85 × 2 = 1.8 -- nurture = 2.5 × 1.4 × 1.25 = 4.375 -- chance = 0.10 × 1.8 × 4.375 = 0.7875 → **~79%** - -Same base rate as example 1, same engine — but nature and a badly-run cell have turned a 2% pawn into -a near-certainty. The player did that, lever by lever. - -### Worked example 3 — hitting the cap - -A fully stacked monster (Nature clamps to 1.0), in despair (×2.5) and held & unhappy (×1.4), in a -lawless colony where Justice has set deterrence to 1.4. Base rate 10%: - -- nature term = 0.1 + 1.0 × 2 = 2.1 -- nurture = 2.5 × 1.4 × 1.4 = 4.9 -- raw chance = 0.10 × 2.1 × 4.9 = 1.029 -- capped at **85%** - -The raw product blew past 100%; the cap reins it to 85%. Even here, a 15% sliver of "not today" -survives. That sliver is deliberate — it keeps the worst pawn a character with a bad day coming, not a -scripted event. - ---- - -## The fixed roll — characters, not a dice cup - -Each pawn's answer to "would they?" is **fixed** by two things: who the pawn is (their permanent -identity) and which behaviour is being asked about. It is not re-rolled from scratch each time. This is -the single most important design decision on this page, and it's worth being precise about why. - -**Save/reload stability.** Because the answer is tied to the pawn's permanent identity and the specific -question — not to the live random stream — asking "would they?" gives the same answer before and after -a save/reload, as long as the inputs (traits, mood, reform) are the same. You can't scum a reload to -re-roll a pawn into a different person. *Who* they are doesn't shift under them on a reload. - -**A character, not a moment-to-moment lottery.** If the game flipped a fresh coin every tick, any pawn -would eventually do anything if you waited long enough. Fixing the roll instead makes "would this pawn -pocket a shiv?" a settled fact about that pawn under those conditions — what makes them a character, -not a dice cup. - -**Live circumstance still bites.** The roll freezes the *identity*, not the *situation*. Nurture is -recomputed live, so as mood collapses or reform hardens, the same pawn's chance climbs and the same -fixed coin can flip from "no" to "yes." The pawn who wouldn't have acted last month acts now — not -because the dice changed, but because you let their world get worse. - -**Different questions, independent answers.** Each behaviour is its own separate question, so the -answers don't leak into each other: a pawn who would pocket a shiv is not therefore a pawn who would -inform on a cellmate. One pawn can be reliably one kind of trouble and reliably not another, and that -pattern is stable across the whole game. - ---- - -*Part of the **Institution** suite.* diff --git a/Secured-Context.md b/Secured-Context.md deleted file mode 100644 index 98d5c89..0000000 --- a/Secured-Context.md +++ /dev/null @@ -1,88 +0,0 @@ -# Secured Context — the kind of hold a pawn is under - -The suite has a rule that looks small and is load-bearing: **nothing keys off "is this a prisoner."** -It keys off the *kind of hold* a pawn is under. That one step of indirection is why a ward patient, a -slave, and (later) anyone inside a secure zone get the same concealment, search, schedule, and needs -machinery for free, without any feature hard-coding a single pawn status. - -A pawn's secured context boils down to one of three kinds and the question "who, if anyone, may search -them." Everything downstream reads that, so a new feature works across every kind of hold the day it's -written, and a new *kind of hold* works across every existing feature the day it's added. - ---- - -## The three kinds - -| Kind | Who it is | May search them | Can conceal? | Held against their will? | -|---|---|---|---|---| -| **Free** | a free colonist | *no one* — until a secure-area or policing layer grants standing | **yes** — they can hoard | no | -| **Prisoner** | a prisoner of the colony | the **warden** | yes | **yes** | -| **Slave** | a slave (Ideology DLC) | the **overseer** | yes | **yes** | - -Two subtleties fall out of this table: - -- **Free colonists can still conceal.** A free colonist can hoard contraband, but no one has standing - to search them until a secure-area or policing layer grants it. Freedom isn't innocence — it's only - the absence of an authority allowed to check. -- **Prisoner and Slave differ only in who holds the keys.** Both are "held"; the search authority is - the warden for one and the overseer for the other. Features that only care "is someone entitled to - search this pawn" read whether the pawn is *held* and never branch on which. - -## Two questions, two axes - -The context answers two different questions, and picking the right one is the whole skill of using it: - -| Question | True for | Ask it when you care about… | -|---|---|---| -| **Is this pawn held?** | Prisoner, Slave | **custody** — who is under the colony's control, who can be disciplined, whose cell can be searched | -| **Could this pawn be hiding something?** | Free, Prisoner, Slave (any real pawn) | **contraband** — who could be *hiding* something, regardless of status | - -For example, [Propensity](Propensity.md)'s Nurture uses *held* in its "held & unhappy compounds" lever -— it only wants to pile the ×1.4 penalty on a pawn the colony actually holds and mistreats, not on a -grumpy free colonist. A warden-search feature, by contrast, cares who *could* be hiding something to -decide who's even worth checking, and then checks standing to decide whether it's *allowed* to. - ---- - -## How a pawn gets classified - -Any pawn resolves to one context, or to **nothing at all** if the suite doesn't model them: - -- Animals, mechs, and the dead are simply not the suite's business — they resolve to nothing, and - every sweep and check skips them without a special case. -- A pawn is tested as **prisoner** first, then **slave**, then **free colonist**. So a pawn who is - somehow both a colonist and imprisoned is classified by their *hold* first. - -Keeping "nothing at all" separate from "a free pawn we track" is deliberate: there's a real difference -between "a free pawn we watch" and "a pawn we don't model at all," and collapsing them would let -non-colony pawns leak into colony machinery. A single sweep can walk every prisoner, slave, and -colonist on a map in one pass, skipping everything that resolves to nothing. - ---- - -## Why not just "prisoner"? - -This is the design decision the whole page exists to justify. If every feature checked "is this pawn a -prisoner" directly, then: - -- adding **slaves** to a feature would mean revisiting every feature; -- adding a **ward patient** mode would mean revisiting every feature; -- adding a future **secure-zone** concept would mean revisiting every feature. - -By routing all of them through one question — *what kind of hold is this?* — a new kind of hold is -added *once*, and every existing feature inherits it. The concealment, search, and needs machinery -never has to learn what a slave is; it only ever asked whether the pawn is *held* and whether they -*could conceal*. - -### The deliberately-absent Ward kind - -There's no separate "ward patient" kind, and its absence is intentional. A committed ward patient -**is** a prisoner in the game's own sense — Institution: Ward builds its committed-patient mode on top -of vanilla's prisoner system — so such a pawn already counts as **Prisoner** here, with no special case -and no dependency from Core (or Contraband) onto Ward. Every feature treats a ward patient exactly as -it treats any prisoner. The right amount of new work to support Ward's hold semantics was zero, and -that's the payoff of keying off the kind of hold instead of the label. - ---- - -*Part of the **Institution** suite.* diff --git a/Treatment-Engine.md b/Treatment-Engine.md deleted file mode 100644 index e54e66b..0000000 --- a/Treatment-Engine.md +++ /dev/null @@ -1,94 +0,0 @@ -# The Treatment Engine — shared rehabilitation - -*The shared maths behind every "fix a held pawn over time" system in the suite.* - -Core carries one more thing every rehabilitation-style system needs and none should own alone: the -maths of a **treatment programme**. Sustained attention in a secured facility reduces a marked -condition, the room's quality helps or hurts, and once there's nothing left to reduce a **recovery -track** builds toward a state where the pawn can be discharged. - -It exists for the same reason the propensity engine does. Two systems want the identical loop pointed -at different things — **Ward** treats the mental illness that got a pawn committed; **Justice** -rehabilitates the disposition that got one imprisoned — and without a shared engine each would grow its -own copy and drift apart. Core owns **only the maths**. Which interaction enrols a pawn, which -conditions and moods carry the flavour, which jobs run the sessions, and which alert fires on discharge -all live in the mod using it. - -> The engine does something only when there's a real condition to work through, and does nothing -> otherwise. A colony that never marks anything treatable never notices it exists. - ---- - -## How treatment plays out - -A condition has to be **marked treatable** before a programme can touch it (Ward marks mental illness -this way; a modder or player can mark anything — see the [Modder API](Modder-API.md) page). Once a -condition is marked, treatment runs in sessions: - -1. **Each completed session removes a slice of the condition's severity.** The base amount is **0.12 - severity per session**, *before* it's scaled by the treating pawn's skill, the facility's quality, - and how much of the session that patient actually gets. When a condition's severity reaches zero - it's gone. -2. **A full course is several sessions by design.** The programme has to be *sustained* — you can't - fix a pawn in a single visit. -3. **Once nothing is left to treat, continued care builds a recovery track** from 0 toward 1 - (discharge-ready). Fix the illness first, then stabilise. -4. **The recovery track decays on its own if you stop.** Recovery you stop maintaining slips back down - — which is what makes the whole thing a loop you keep up, not a one-time unlock. - ---- - -## The numbers - -### Facility quality - -The room the treatment happens in scales every session between **0.5×** (grim) and **1.5×** -(excellent): - -| Room | Factor | -|---|---:| -| Bare (0 impressiveness) | 0.60 | -| Decent (~48 impressiveness) | 1.00 | -| Impressive (108+ impressiveness) | 1.50 (capped) | -| Outdoors / no room | 0.75 | - -The limits are deliberate: a grim, filthy, cramped facility heals worse and a calm clean one better, -but a palace can't trivialise the work the programme costs (1.5× ceiling), and even treating a pawn out -in the open is a poor makeshift room (0.75×), not a hard zero. - -### Reducing a condition - -Each marked condition drops by **0.12 × the session's combined strength** per session, and vanishes -when it hits zero. That combined strength is the treating pawn's skill × the facility quality above × -the patient's share of the session — so all three inputs matter, and a good therapist in a good room -working one-on-one is worth many times a poor one splitting attention in a bad room. - -### Building recovery - -The recovery track is a plain 0-to-1 progress bar toward discharge. Continued care adds to it (capped -at 1.0) and — crucially — it carries a slow decay, so it slips back down without sustained attention. -The mod using the engine decides what reaching the top actually *unlocks* (Ward: a "ready for -discharge" alert). - ---- - -## Who uses it - -- **[Institution: Ward](https://git.onetick.ninja/flan/rimworld-ward)** — psychiatric care. Marks - mental-illness conditions treatable (Rim Disorders' depression, anxiety, PTSD, and OCD, when that mod - is present), runs warden counselling sessions, and builds a recovery track toward a "ready for - discharge" alert. The reference example. -- **Institution: Justice** — rehabilitation. Its *reform* score is the disposition axis punishment - moves; the recovery track is the natural home for a *sustained rehabilitation programme* that gates - parole on the same shared engine, so the two systems agree on "getting better" instead of each - inventing it. - -"Reduce the condition, *then* build recovery" is the shape Ward uses, but it isn't forced: a -rehabilitation system with no clinical condition to clear (like Justice's reform) can build a recovery -track from the very first session and read its level to gate a parole. - -The point, exactly as with propensity: one engine, two uses, no drift. - ---- - -*Part of the **Institution** suite.* diff --git a/Tunnels.md b/Tunnels.md new file mode 100644 index 0000000..18c828b --- /dev/null +++ b/Tunnels.md @@ -0,0 +1,158 @@ +# 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.* diff --git a/Warden-Search.md b/Warden-Search.md new file mode 100644 index 0000000..cc54943 --- /dev/null +++ b/Warden-Search.md @@ -0,0 +1,181 @@ +# 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.*