institution/ROADMAP.md

The Institution suite — master roadmap

A set of RimWorld mods about what an institution does to the people inside it — and the crime, policing, and justice that put them there. Each mod stands alone; together they form one system.

North star

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

The same seeded disposition engine that drives the piss spree (WouldFoulPeople = disposition × circumstance, fixed per pawn), generalized. The suite is the two halves of that:

• Pre-arrest — colonists commit crimes on a spectrum; a policing layer discovers, investigates, and catches them. Arrest is the hinge.
• Post-arrest — prison, contraband, improvised weapons, escape, wards, secure areas, the daily life of the held, and the path back out (parole / discharge / manumission).

The load-bearing principle: SECURED CONTEXT, not "prisoner"

Nothing hard-codes "prisoner." The subject of every held-person system is a secured context — a pawn held in a controlled space, subject to search, following a regime:

Context	Members	Authority	Release path
Prison	prisoners	warden	parole
Psych ward (Ward mod)	committed patients	orderly / warden	discharge (when treated)
Slavery (Ideology)	slaves	overseer	manumission (Ideology)
Secure area	anyone inside a zone	assigned guard	leave the zone

A committed patient rides the vanilla prisoner rail (Ward's Ward_PsychiatricCare mode), so contraband, search, schedule, needs, and visitation already apply to ward patients for free — and to slaves via a small Ideology-gated extension. Every system below reads SecuredContextOf(pawn), never IsPrisonerOfColony directly. Build prisoner-first, against the predicate, and ward + slave + secure-area fall out without a rewrite.

Design tone: standards are low on the rim. Needs and expectations for the held are modest — a prisoner does not expect a spa. Don't over-model comfort; a little goes a long way.

---

Suite modules

Mod	Scope	Status
Foul Play	throw a container of something off a body; vessels + substances + Piss Nuke flagship	built
Institution: Contraband	conceal / improvise / search / confiscate / intake / escape / secure-areas	building
Institution: Ward	involuntary psychiatric commitment — the third pawn state	built
Institution: Regime	daily schedule (vanilla Restrict) + modest needs + visitation, for every secured context	planned
Institution: Justice	the crime loop (commit → discover → investigate → attribute → arrest), policing officer, parole/discharge/manumission	planned
Institution: Discipline	security classification / segregation, punishment-as-order, corruption	planned
Institution: Gangs	prisoner & colony gangs, rivalries, contraband networks	planned

Seven mods is the ceiling. Prefer folding a slot into an existing module over minting a new one.

---

Regime — daily life of the held

Schedule (use vanilla, don't reinvent)

RimWorld already has Pawn_TimetableTracker + TimeAssignmentDef and the Restrict tab. Extend that to secured pawns rather than building a new regime UI. Prison Labor (1899474310, 176k) already puts force-to-work prisoners in the Restrict grid — build on that pattern, don't fight it.

• Give secured pawns a timetable; surface it in the Restrict tab.
• Two new TimeAssignmentDefs cover the prison-specific blocks vanilla lacks: Yard (go to a designated yard/commons — ties to Prison Commons) and Lockup (confined to cell). Eat/Sleep/ Work/Joy map to existing assignments.
• A think-tree branch makes secured pawns honour their timetable (they already have a prisoner think-tree branch to hook).
• Ward routine and slave work-schedule are the same machinery, different default timetables.

Needs (modest — standards are low)

Do NOT build a full Prison Architect needs sim. One or two low-stakes needs, keyed to the schedule:

• Yard / open air — satisfied by the Yard block. Vanilla already has the Outdoors need; check whether it applies to secured pawns and lean on it before adding one.
• Safety — a modest mood factor from feeling safe (few violent cellmates, guards present).
• Recreation is already covered by Prisoner Recreation (815726158) — don't rebuild.

Keep the magnitudes small. A satisfied schedule = a quiet wing; neglect = the disposition engine tips more pawns over the edge (feeding contraband, breaks, gang recruitment).

Visitation

Off-map visitors and related pawns visit the held. A genuine greenfield gap — Hospitality is guests only and never touches prisons.

• A visitation room role; scheduled visiting hours (a schedule block).
• A prisoner/patient with family or faction ties gets visits; the warden/orderly supervises.
• Feeds a modest Family/social mood boost. Thematically strongest for the ward — a committed patient's family visiting is exactly right — and it is a supply route for contraband (a visitor smuggles something in → Contraband's conceal system).

---

Justice — the crime loop (the missing middle)

The heart. Without discovery + investigation, "crime" is just a random bad event, not something you police. The loop:

commit → discover → investigate → attribute → arrest → (held) → release

• Commit. A colonist acts on their propensity (nature: traits incl. VTE 2296404655 646k kleptomaniac/pyromaniac — integrate as inputs, don't rebuild; nurture: our stat). Crimes: theft, contraband possession, sabotage, arson, assault, at the serious end murder.
• Discover. The colony learns a crime happened: missing goods, a body, damage, filth, or a witness. Discovery is not automatic — a crime in an unwatched place may go unnoticed.
• Witnesses / informants. A colonist near the act may witness it → report, be intimidated into silence, or inform for favour. The cheap, characterful detection layer.
• Investigate. A policing officer works the scene: evidence, opportunity, the stolen goods in someone's concealed stash (ties to Contraband search!), narrowing suspects.
• Attribute. Evidence points to a pawn. Confidence, not certainty — wrongful accusation is a possible, dramatic failure.
• Arrest. Vanilla's one law verb. The hinge into the held systems.

Policing officer

Guarding is owned (Guards For Me 1855885448, 88k — patrol/bodyguard, external threats only), the catching is not. Build the officer who investigates and arrests criminal colonists; lean on Guards For Me's guard role where present rather than reinventing patrol.

Parole / discharge / manumission — release, driven by IDEOLOGY

The payoff that makes Ward's treatment and good behaviour mean something. Release is not a flat timer — the colony's Ideology precepts decide the policy (MayRequire Ideology; a vanilla fallback for non-Ideology games):

• A harsh / execution-favouring ideoligion rarely paroles (executes or works-to-death instead).
• A rehabilitative / lenient ideoligion paroles readily on reform + good behaviour.
• Parole (prisoner), discharge (ward patient, when treated — the Ward analog), manumission (slave, Ideology's own freeing) are one mechanism with three faces.
• A released, reformed pawn has reduced recidivism — integrate with Prisoner Realism's recidivism (3760196312) rather than duplicate it: our reform lowers its return chance.

Sentencing timers exist (Prisoner Sentencing 3736998871) — defer to it; add only the ideology-driven decision, not another timer.

---

Discipline — control

• Classification / segregation — make the wings players already build MEAN something. Players already hand-build min / medium / max / solitary blocks with zones, cells and locks. RimWorld just has no notion of who belongs where or whether they are correctly placed. We do not replace the building — we add the intelligence layer on top of it, and it becomes the router that connects the whole suite:

  • Grade (information). Each secured pawn gets a risk grade computed from disposition × traits × history (escape attempts, contraband made, guards attacked, murder on record). The player stops guessing who is dangerous — the game tells them "this one is max."
  • Assignment + misplacement flag (enforcement). Tag a wing's grade; the system routes prisoners to the matching wing and warns when a max-grade pawn sits in a min cell. Vanilla gives zero feedback here today.
  • Dynamic re-classification (dynamics). Grade moves with behaviour: an escape attempt or a shanking upgrades them; Ward treatment + good conduct + time downgrades them. This wires classification straight into the behaviour loop.
  • Grade gates the other systems (the payoff). Grade drives search frequency (Contraband — max = frisked often), privileges (Regime — yard/visitation/recreation restricted by grade), escape risk (a dangerous pawn in a weak cell escapes more), and reform eligibility (Justice).
  • The tension that makes it a decision. Over-classify (everyone in max/solitary) = safe but mood craters, reform fails, ideology frowns on cruelty, and warden-hours explode. Under-classify (everyone min) = cheap and happy but they walk out. Classifying correctly is the game; we supply the information and the consequences that make it one.

  No mod auto-classifies (manual wing-building is emergent player behaviour, not a mod), so the system is an uncontested gap even though the physical tiers are common.

• Punishment as a player order. Issue solitary / lockdown / privilege-revocation as a discipline action. Distinct from Prisoner Realism's passive solitary toll — we add the order and its interface; defer the mood consequence to Realism where present.

• Corruption. Wardens/guards take bribes, smuggle, or look away — a guard-integrity stat. Seeds the bent-warden contraband supply route already in Contraband's plan.

---

Gangs

Untouched by any mod. Prisoners (and colonists) form gangs / factions with rivalries that drive violence and run contraband networks. Ties to disposition (who joins), contraband (what they move), and classification (segregate rivals). The richest, latest module — build after the loop works.

---

Build order (fills the meta-gap: don't build it all at once)

1. The crime loop core — discover + witnesses + investigate + attribute. Without it the whole crime thesis is inert. Build before individual crime types.
2. Regime — schedule (vanilla Restrict) + one or two modest needs. Cheap, high-value, and it feeds the disposition engine (neglect → crime).
3. Visitation — greenfield, thematically strong for the ward, doubles as a contraband route.
4. Parole / discharge / manumission — gives Ward and good behaviour a payoff; ideology-driven.
5. Classification, then punishment-orders, then corruption.
6. Gangs — last; needs the rest in place.

Already in flight (Contraband/Foul Play): hooch, improvised weapons, fire-starter, escape tools, intake search, secure areas. See Contraband ROADMAP.

Compatibility — the non-negotiable

The suite must load and run cleanly alongside the all-time most-subscribed Workshop mods, not just prison-adjacent ones — that is the load order most players actually run. The harness (Tools/run-compat-test.sh in the Ward repo) boots a real headless RimWorld with the suite plus this stack loaded at once and fails on any error naming our code.

Baseline stack (all 1.6, verified subs):

• Frameworks: Harmony (3.2M) · HugsLib (2.5M) · Vanilla Expanded Framework (2.0M) · Humanoid Alien Races (1.1M).
• Ubiquitous gameplay/AI: Pick Up And Haul (1.7M) · Common Sense (1.05M) · Simple Sidearms (954k) · Vanilla Furniture Expanded (1.08M) · EdB Prepare Carefully (1.67M).
• UI (load-order neighbours): RimHUD (1.5M) · Allow Tool (1.36M) · Interaction Bubbles (1.15M) · Camera+ (997k).
• Weapon/our-domain risk: Vanilla Weapons Expanded (985k) · VFE Furniture Security (865k) · Vanilla Brewing Expanded (589k) · Hospitality (798k).
• Prison-adjacent (design overlap): Prison Labor · Prison Commons · Locks · Restraints · Custom Prisoner Interactions · Prisoner Realism · Prisoner Recreation · Dubs Bad Hygiene · Psychology · Rim Disorders · More Mental Breaks.

Combat Extended (387k, 1.6) gets its OWN dedicated pass, not the mixed stack: it overhauls verbs, projectiles, damage and armour — exactly our thrown-weapon surface — so an ambiguous failure in a 25-mod stack would be useless. Loading-clean-under-CE is a must-have; a tuned CE armour-penetration patch (MayRequire) is a strongly-recommended follow-up, not a release blocker.

How the suite earns this: zero-Harmony cores, Contraband optional via a LoadFolders bridge, every DLC/mod tie-in MayRequire-gated, and new content registered by capability (IsWeapon, IsDrug, category) rather than hard-coded lists — so modded weapons, drugs and races are covered without being named.

Self-complete, dependency-free — the standing rule

Two rules, and the second is the sharper one:

1. Judge by QUALITY, not sub count. If an incumbent is actually good, keep it. A genuinely good mod — even a small one — is worth coexisting with rather than rebuilding: don't waste effort duplicating something done well (Prisoner Realism at 11k is a good deep sim → keep it). Only build our own where the incumbent is thin, absent, or mediocre on one of our crucial loops (Prisoner Recreation just flips vanilla Joy → trivially ours; the 334-sub crime mod is niche → the slot is open). Sub count is a hint, not the test.

2. No hard dependencies. Every crucial loop is self-complete. The suite must be a whole, working system on its own. Third-party mods are coexistence targets that ENHANCE, never requirements. Where we integrate (Ideology precepts, Prisoner Realism's recidivism, Prison Labor's regime), it is always MayRequire-soft: the feature lights up if the mod is present and the loop still closes without it.

What this changes vs. a naive "defer to whoever got there first":

• Recreation is ours to enable. Prisoner Recreation (38k) and Prisoner Realism (11k) ship no custom need — they just flip on the vanilla Joy need for prisoners. We do the same in our needs system: idempotent, coexists, zero dependency, no citing.
• Release-outcome / recidivism — build a modest self-complete version (reformed → less return; abused → returns hostile). Prisoner Realism's deeper recidivism coexists; we don't require it.
• Solitary/isolation consequence — a light version of our own so Discipline is self-complete; Realism's deeper toll coexists.
• Escape is already self-complete: vanilla mental-break breaks + our disposition-driven arming
  • our patient tunnel. Realism's lockpick/ringleaders are enhancements on top, not gaps we leave.

Genuinely leave alone (giant + redundant + not a gap in our loops): forced labor (Prison Labor 176k), hygiene (Dubs Bad Hygiene 632k), crime traits (Vanilla Traits Expanded 646k — we consume them as nature inputs), guest hosting (Hospitality 798k). Coexist with all; depend on none.

Prior-art sweeps done (2026-07-14/15)

Uncontested gaps, safe to build clean: contraband/search, improvised weapons, keep-inventory intake, secure-area search, nurture criminality stat, investigating officer, patient escape, visitation, classification, punishment-order, gangs, corruption. Partial (build the uncovered slice only): prisoner timetable, yard/safety/privacy needs, evidence/forensics investigation, active snitch/informant, reform-and-ideology-driven parole. The only prior art in the crime/parole space (Rimworld Law and Order, 334 subs) fails the popular bar, so that slot is open — build it without duplicating that niche mod exactly.

Architecture already honors rule 2

Zero hard dependencies anywhere: Foul Play stands alone, Contraband is optional to it (the LoadFolders bridge loads only when both are present), Ward stands alone, and every DLC/mod tie-in is MayRequire. No suite mod requires another suite mod or any third-party mod.

AI disclosure

Designed and built with substantial assistance from Claude (Anthropic).