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

Wiki: player-facing rewrite of every layer + add a scenario FAQ, linked from Home

Browse Source
This commit is contained in:
flan
2026-07-16 02:18:25 +00:00
parent ff703271ba
commit 8250dcb369
32 changed files with 1654 additions and 2510 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Wiki/policing/Deterrence.md
+53 -90
View File
@@ -2,22 +2,22 @@
*The connection that turns the pipeline into a cycle.*
This is the module that makes policing **govern** rather than merely clean up. Everything else in
Justice reacts to one pawn: this reactor's *state* is the whole colony, and it feeds **back** into
every pawn's disposition. Crime that goes unanswered emboldens everyone a little; visible justice
deters everyone a little. The reason to punish is not just this prisoner — it is the message it sends
the rest, and here that message is a number they all read.
This is the part that makes policing **govern** rather than merely clean up. Everything else in Justice
reacts to one pawn: this reacts to the *whole colony*, and it feeds **back** into every pawn's
disposition. Crime that goes unanswered emboldens everyone a little; visible justice deters everyone a
little. The reason to punish is not just this prisoner — it is the message it sends the rest, and here
that message is a number they all read.
---
## The climate of order
Every map carries a `MapComponent_Deterrence` holding one value:
Every colony carries one order value:
| | |
|---|---|
| **Range** | `0.0` (lawless) … `1.0` (iron) |
| **Baseline** | `0.5` — an ordinary colony |
| **Range** | 0.0 (lawless) … 1.0 (iron) |
| **Baseline** | 0.5 — an ordinary colony |
| **Below baseline** | crime pays; dispositions run **hot** |
| **Above baseline** | order holds; dispositions run **cool** |
@@ -25,50 +25,40 @@ It is nudged by two events and, left alone, forgets.
### The nudges
| Event | Source | Nudge | Written by |
|---|---|---|---|
| A crime, unanswered | `Justice.RecordCrime(perp)` | **−0.08** | Justice, Gangs (fights) |
| Visible justice done | `Justice.RecordPunishment(map)` | **+0.12** | Justice (`Discipline.Punish`) |
| Event | Nudge |
|---|---|
| A crime, unanswered | **−0.08** |
| Visible justice done (a punishment) | **+0.12** |
Both clamp the result to `[0, 1]`. Note the asymmetry: **punishment (+0.12) outweighs crime (−0.08)
Both stay clamped to the 0–1 range. Note the asymmetry: **punishment (+0.12) outweighs crime (−0.08)
by 1.5×.** A colony that answers every offence does not merely break even — it ratchets *above*
baseline into "order holds" territory. This is the deterrence dividend, and it is deliberate: justice
seen to be done buys more order than the crime cost.
`RecordCrime` also writes the record — it increments `crimesCommitted` and stamps `lastCrimeTick` on
the perpetrator — so the same event that moves the climate is the event classification and parole
later see. `RecordPunishment` moves only the climate; the *record* side of punishment (the reform
shift) is [Discipline](Discipline-and-Reform.md)'s job.
The same crime that moves the climate also marks the culprit's record — the offence that shifts the
colony's mood is the one classification and parole will remember later. A punishment moves only the
climate; the reform side of a punishment — how the offender themselves changes — is
[Discipline](Discipline-and-Reform.md)'s job.
### The drift
```
every 2500 ticks: level = MoveTowards(level, 0.5, 0.0015)
```
Memory fades. With nothing happening, the climate creeps back toward ordinary at about **0.0015 every
in-game while (roughly one nudge every 2500 ticks)** — which works out to:
Memory fades. With nothing happening, the climate creeps back toward ordinary at **0.0015 per step,
one step every 2500 ticks** — which works out to:
**drift per in-game day ≈ 0.036**
```
drift per in-game day = (60000 / 2500) * 0.0015 = 24 * 0.0015 = 0.036 / day
```
So a single unanswered crime (`−0.08`) takes roughly `0.08 / 0.036 ≈ 2.2 days` to heal on its own —
or one punishment (`+0.12`) to over-answer instantly. An iron colony you stop maintaining slides back
to baseline over about two weeks; it does not stay stern for free.
So a single unanswered crime (−0.08) takes roughly `0.08 / 0.036 ≈ 2.2 days` to heal on its own — or
one punishment (+0.12) to over-answer instantly. An iron colony you stop maintaining slides back to
baseline over about two weeks; it does not stay stern for free.
---
## The feedback — how it reaches every pawn
This is the loop. The climate is read back into `Propensity.Nurture` (in Core) as a multiplier:
This is the loop. The climate is read back into every colonist's upbringing as a multiplier on their
propensity:
```
DeterrenceFactor(pawn) = Lerp(1.3, 0.7, level) // = 1.3 - 0.6 * level
Nurture(pawn) = ... * DeterrenceFactor(pawn)
```
| `level` | Factor | Effect on every pawn's disposition |
| Order level | Factor | Effect on every pawn's disposition |
|---|---|---|
| 0.00 (lawless) | **1.300** | +30% hotter — crime pays, everyone feels it |
| 0.30 | 1.120 | +12% |
@@ -79,55 +69,42 @@ Nurture(pawn) = ... * DeterrenceFactor(pawn)
Two things to notice:
- **Baseline is the neutral point, by design.** A default colony sits at `0.5`, which is a factor of
exactly `1.0` — ordinary order neither inflames nor calms. That symmetry is deliberate. If baseline
ran hot (as an earlier tuning did), ordinary order would nudge propensity up, breed a little more
crime, drop order, and feed a slow runaway. Neutral-at-baseline means only a colony that lets order
*slide below* ordinary earns the hot multiplier, and only one that pushes *above* it earns the calm.
- **The swing is `0.7×` to `1.3×`, symmetric around `1.0`** — a `±30%` spread applied to *everyone's*
nurture at once. This is the multiplier that makes catching one pawn matter to the disposition of
- **Baseline is the neutral point, by design.** A default colony sits at 0.5, which is a factor of
exactly 1.0 — ordinary order neither inflames nor calms. That symmetry is deliberate. If baseline
ran hot, ordinary order would nudge propensity up, breed a little more crime, drop order, and feed a
slow runaway. Neutral-at-baseline means only a colony that lets order *slide below* ordinary earns
the hot multiplier, and only one that pushes *above* it earns the calm.
- **The swing is 0.7× to 1.3×, symmetric around 1.0** — a ±30% spread applied to *everyone's*
disposition at once. This is the multiplier that makes catching one pawn matter to the disposition of
the rest.
### PolicingBootstrap — reconnecting the loop across the mod boundary
### When it applies
Core keeps `Propensity.DeterrenceFactor` as a neutral seam — a `Func<Pawn,float>` that returns `1f`
until something fills it. Core alone never has to know Justice exists; that one seam is what lets Core
stay a dependency-free leaf while the deterrence loop runs *through* it.
At startup, `PolicingBootstrap` fills the seam:
```csharp
Propensity.DeterrenceFactor = pawn => {
var d = pawn?.Map?.GetComponent<MapComponent_Deterrence>();
return d != null ? Mathf.Lerp(1.3f, 0.7f, d.Level) : 1f; // neutral (1.0) at baseline 0.5
};
```
So **only when Justice is installed** does the climate bend disposition; without it, Core reads a flat
`1.0` and pawns are indifferent to order. This is the deterrence feedback loop, reconnected across the
mod boundary without Core ever depending on the justice layer. (If the pawn is off-map — caravan, in
transit — there is no map component, and the factor falls back to a neutral `1.0`.)
This bending of behaviour only happens while **Policing is installed**. Core on its own reads a flat,
neutral 1.0 — colonists are indifferent to order — and only Policing wires the climate into their
disposition. A colonist who is off the map (in a caravan, in transit) has no local climate to read, so
they fall back to neutral too.
---
## Worked example — a day at the institution
The colony starts at baseline `0.5` (factor `1.05`). Over one day:
The colony starts at baseline 0.5 (factor 1.05). Over one day:
| Step | Event | `level` | Factor |
| Step | Event | Order level | Factor |
|---|---|---|---|
| start | — | 0.50 | 1.050 |
| 1 | Prisoner A shanks a guard (crime, unanswered) | 0.42 | 1.106 |
| 2 | Prisoner B foments trouble (crime, unanswered) | 0.34 | 1.162 |
| 3 | Warden punishes A (`RecordPunishment`) | 0.46 | 1.078 |
| 4 | Warden punishes B (`RecordPunishment`) | 0.58 | 0.994 |
| 3 | Warden punishes A | 0.46 | 1.078 |
| 4 | Warden punishes B | 0.58 | 0.994 |
| overnight | nothing happens, drift ≈ −0.036 toward 0.5 | 0.544 | 1.019 |
Two crimes cost `−0.16`; two punishments returned `+0.24`. The colony ends the day at `0.58` —
**above** where it started — because punishment out-answers crime. Every pawn's disposition dipped
hotter as the crimes landed (`1.05 → 1.16`) and then cooled below neutral once order was reasserted
(`0.994`). By morning the drift has begun erasing the gain, and if nothing keeps the pressure on, the
colony sinks back to its slightly-hot baseline over the next couple of weeks.
Two crimes cost −0.16; two punishments returned +0.24. The colony ends the day at 0.58 — **above**
where it started — because punishment out-answers crime. Every pawn's disposition dipped hotter as the
crimes landed (1.05 → 1.16) and then cooled below neutral once order was reasserted (0.994). By morning
the drift has begun erasing the gain, and if nothing keeps the pressure on, the colony sinks back to its
slightly-hot baseline over the next couple of weeks.
That arc — hot when crime pays, cool when justice is seen, forgetful when neither happens — is the
whole reason discipline is not inert. You are not punishing a pawn; you are setting the temperature of
@@ -140,27 +117,13 @@ the room.
- **Answer crime, visibly and promptly.** Each punishment is worth 1.5 crimes of order. A colony that
reliably punishes climbs *above* baseline and cools everyone; a colony that lets offences slide
sinks below and heats everyone — a spiral, because hotter pawns commit more crime.
- **Don't coast on a past crackdown.** The climate drifts back to baseline at `0.036/day`. Order is a
- **Don't coast on a past crackdown.** The climate drifts back to baseline at 0.036/day. Order is a
maintenance cost, not a one-time purchase.
- **Push past baseline if you want calm.** Neutral disposition needs `level ≈ 0.571`; ordinary
(`0.5`) still runs 5% hot. A steady rhythm of caught-and-punished offences is what holds you there.
- **A lawless spell is self-feeding.** At `level 0.3` every pawn is `1.19×` more disposed; more crime
follows, driving the level lower still. Break the cycle with punishments, not patience.
---
## For modders
```csharp
Justice.RecordCrime(perpetrator); // -0.08 climate, +1 crime, stamps lastCrimeTick
Justice.RecordPunishment(map); // +0.12 climate
float level = map.GetComponent<MapComponent_Deterrence>().Level; // raw 0..1
```
`RecordCrime` is the writer any module calls when a pawn does something the colony would police —
Institution: Gangs calls it on rival fights, for instance. `RecordPunishment` is called by
`Discipline.Punish`. The component and statics live in the `Contraband` namespace (shared across the
suite since Justice's extraction from Contraband).
- **Push past baseline if you want calm.** Neutral disposition needs an order level of about 0.571;
ordinary (0.5) still runs 5% hot. A steady rhythm of caught-and-punished offences is what holds you
there.
- **A lawless spell is self-feeding.** At an order level of 0.3 every pawn is 1.19× more disposed; more
crime follows, driving the level lower still. Break the cycle with punishments, not patience.
---
Wiki/policing/Home.md
+13 -12
View File
@@ -4,8 +4,8 @@
RimWorld 1.6 mods.*
Vanilla RimWorld keeps a rap sheet no one reads, and your own colonists never break the law. Policing
gives the colony a **climate of law and order** over the shared criminal record: colonists offend on a
seeded propensity spectrum, the law catches them, and catching one changes the disposition of the rest.
gives the colony a **climate of law and order**: colonists offend on a spectrum of criminal
propensity, the law catches them, and catching one changes how the rest behave.
> **Catching and punishing one pawn changes the disposition of the rest.**
@@ -18,33 +18,34 @@ reason to punish an offender is the message it sends everyone else quietly decid
| Page | What it covers |
|---|---|
| **[Policing](Policing.md)** | Colony crime on the propensity spectrum, witnesses and the constable work type, the weighed arrest and resistance, prison riots, the recidivism alert. |
| **[Deterrence](Deterrence.md)** | The colony's climate of order (0 lawless … 1 iron), moved by crime and punishment, drifting to baseline, fed back into every pawn's disposition through Core's seam. |
| **[Policing](Policing.md)** | Colony crime on the propensity spectrum, witnesses and the constable's investigation, the weighed arrest and resisting it, prison riots, and the recidivism alert. |
| **[Deterrence](Deterrence.md)** | The colony's climate of order (0 lawless … 1 iron), moved by crime and punishment, drifting back to baseline, and fed back into every colonist's disposition. |
At load, **`PolicingBootstrap`** fills the neutral deterrence seam Core leaves open — reconnecting the
feedback loop across the mod boundary without Core ever depending on the policing layer.
The climate of order only steers your colonists while Policing is installed. Core on its own keeps the
records but leaves behaviour untouched; add Policing and the feedback loop comes alive — visible
justice starts calming the colony, unanswered crime starts emboldening it.
---
## The one shared record
Policing keeps no per-pawn crime state of its own. It reads and writes the single `CriminalRecord` that
**Institution: Core** holds for every pawn — the same record Contraband, Corrections, and the gang
systems read. `RecordCrime` writes the `crimesCommitted` / `lastCrimeTick` columns; Corrections grades
and reforms over the same numbers.
Policing keeps no crime record of its own. It reads and writes the single criminal record that
**Institution: Core** holds for every colonist — the same rap sheet Contraband, Corrections, and the
gang systems read. A crime here adds to that record; Corrections grades and reforms over the same
history.
---
## Requirements & load order
- **RimWorld 1.6**
- **Institution: Core** — required (the propensity/record engine)
- **Institution: Core** — required (the propensity and record system)
- **Harmony** — required
- Load **after** Core and Harmony.
The prison half — classification, discipline, reform, parole, regime — lives in **Institution:
Corrections**, which depends on this layer for the shared climate of order. A future **Judiciary** layer
(a court that tries and sentences) is reserved as a Core seam; today an arrest imprisons directly.
— a court that tries and sentences — is planned; for now an arrest sends the culprit straight to a cell.
---
Wiki/policing/Policing.md
+24 -29
View File
@@ -12,18 +12,17 @@ deterrence, discipline, parole, regime — without colony crime.
## The loop
```
[crime] → [witnessed / investigated] → [weighed arrest (resist?)] → prison → … → parole → [recidivism]
```
**crime → witnessed / investigated → weighed arrest (resist?) → prison → … → parole → recidivism**
Every stage reads the shared engine (`Propensity`, the `CriminalRecord`, the deterrence meter), so
policing is not a bolt-on — it feeds the same record classification grades on and discipline reforms.
Every stage draws on the same shared systems — each colonist's propensity, the one shared criminal
record, the climate of order — so policing is not a bolt-on: the record it writes is the record
classification grades on and discipline reforms.
## Crime — and why small colonies stay honest
Every ~40 seconds, each free colonist gets a seeded roll to offend. The base rate is low (`0.06`) and
multiplied hard by nature × nurture — almost nobody with an ordinary disposition ever does anything.
But it is *also* multiplied by **crime cover**:
Every ~40 seconds, each free colonist gets a hidden roll to offend. The base chance is low (about
6% per roll) and it is multiplied hard by nature × nurture — almost nobody with an ordinary
disposition ever does anything. But it is *also* multiplied by **crime cover**:
| Free colonists | Crime cover |
|---|---|
@@ -41,8 +40,7 @@ kleptomaniac steals, a bloodlusty pawn assaults, a pyromaniac vandalizes).
## Consequences — the stakes
A crime leaves a mark the colony can *see* (all wrapped defensively — a consequence that finds no
target never breaks anything):
A crime leaves a mark the colony can *see*:
- **Theft** lifts a small stack of the colony's goods and the thief **pockets it**. RimWorld has no
per-person property (stockpiles are communal), so theft is theft from the common store — but the
@@ -58,30 +56,28 @@ target never breaks anything):
## Witnesses and investigation
A crime is not equally solvable. Colonists who were near enough to **see** it are witnesses, and each
is a partial lead — a witnessed crime starts up to `0.8` of the way to solved before anyone lifts a
is a partial lead — a witnessed crime starts up to 80% of the way to solved before anyone lifts a
finger; an unseen one is a **cold case** worked from nothing.
Investigation then accrues evidence toward `1.0` (naming the culprit) two ways:
Investigation then builds evidence toward a full, named solve two ways:
- **Ambient**, scaled by how many colonists the colony can spare (`~0.34` per check per unit of
effort — a few investigated windows).
- **The police work type.** Assign a colonist to *policing* and they walk to open **crime scenes** and
work them, adding a chunk of evidence scaled by their Intellectual + Social skill. A sharp constable
cracks cases fast; a colony that spares no one lets them go cold.
- **Ambient** progress, scaled by how many colonists the colony can spare — a background trickle from
everyone keeping an eye out, faster when the colony has people to spare.
- **The policing work type.** Assign a colonist to *policing* and they walk to open **crime scenes**
and work them, adding a chunk of evidence scaled by their Intellectual + Social skill. A sharp
constable cracks cases fast; a colony that spares no one lets them go cold.
## The weighed arrest
A solved case does **not** mean an automatic arrest. Fellow-colonist cops will not gut the colony to
jail someone over a petty crime — the arrest is a cost/benefit (`ShouldArrest`):
```
arrest ⇔ colony can afford a prison AND severity ≥ 1.5 + value × 3
```
jail someone over a petty crime — the arrest is a cost/benefit call, and it goes ahead only when both
are true: the colony can **afford a prison**, and the crime is **serious enough** to clear a bar that
rises with how valuable the culprit is.
- **Severity** — the crime's kind (theft 1 · vandalism 1.5 · assault 2.5), escalated by the culprit's
record (a rap sheet and prior escapes compound).
- **Value** — 0..1 from the culprit's best skills. A star colonist raises the bar to ~4.5; an
expendable one leaves it at ~1.5.
- **Value** — 0..1 from the culprit's best skills. The bar sits at about 1.5 for an expendable pawn
and climbs by three times the culprit's value — so a star colonist raises it to about 4.5.
- **Capacity** — **below ~5 colonists, or with no prison bed, the colony arrests no one.** A prisoner
plus a warden would cripple a small colony. Capacity ramps up as the colony grows.
@@ -90,22 +86,21 @@ paid, unanswered, erodes the climate of order a little more (crime emboldens).
## Resisting arrest
The disposed do not go quietly (`WouldResist`, seeded nature × nurture):
The disposed do not go quietly (seeded by nature × nurture):
- **Comply** → taken in cleanly (they become a prisoner of the colony — imprisonment is direct, and it
survives guest-management mods like Hospitality).
- **Resist** → the violent turn **berserk**, the rest **flee**. A botched arrest becomes a crisis the
colony must handle the hard way, and openly defying arrest emboldens the lawless.
- **Subdued** → a resister the colony beats down is then **imprisoned** (auto-capture) — the resist
path resolves to a cell once the colony wins the confrontation. One who flees the map gets away.
- **Subdued** → a resister the colony beats down is then **imprisoned** — the resist path resolves to a
cell once the colony wins the confrontation. One who flees the map gets away.
## Prison riots
When the climate of order **collapses** (deterrence at the floor) in a colony holding prisoners, a
neglected prison boils over into a **riot**: disposed prisoners turn violent together, and the unrest
shatters order further. A well-run colony (high deterrence) never sees one — a riot is the thing a
badly-run institution *earns*. It ties the deterrence meter, the propensity engine, and the prison
population into one emergent event.
badly-run institution *earns*.
## Recidivism, made visible