# The Urban-Crime Cell
This is V5's sandbox. The Urban-Crime cell is the GTA / Sleeping Dogs / Mafia
surface where the moment-to-moment loop is **drive, switch, brawl, climb, plan a
job, and run from the stars** — the genre that lives or dies on the texture of a
city: whether a two-protagonist swap mid-chase feels seamless, whether a
fish-market fistfight resolves into a contextual finisher, whether a five-star
military response makes you sweat, and whether a bank job feels _authored_
before a single bullet flies. It carries the largest open-world authoring
footprint of any of the five ruleset cells, and it is the cell that most visibly
proves V5's thesis: that one engine can wear a modern crime sandbox and a dense
undercover beat-'em-up at the same time, held together by a single
reputation-and-heist spine the design calls the **Bureau**.
The cell ships as a cluster of GameFeatures variant modules — a GTA-style
three-protagonist heist campaign (**Heist City**), a Sleeping-Dogs-style
undercover martial-arts campaign (**Street Triad**), and a GTA-Online-style
open-world multiplayer surface (**Urban Online**) — composed over a set of
shared C++ mechanic modules (`V5Heist`, `V5Wanted`, `V5Honor`, `V5Melee`,
`V5Parkour`, `V5Crowd`). The promise is **per-sub-ruleset feel from one mechanic
stack**: a patient Mafia escort drive and a frantic 30-player freeroam read
completely differently to the player, yet both consume the same wanted-heat
curve, the same honor meter, and the same Bureau-XP ledger. This page
inventories what that stack actually does, on the player's side of the screen,
and points at the exact Unreal C++ behind each feature. For the full mode
taxonomy, roster, and the scope this slots into, start at the hub:
[../V5_features.md](../V5_features.md).
## What ships, honestly
**The cell's mechanics are real, compiled, and tested.** Every module named
above exists under `V5/ue/Source/` with a `Public/`/`Private/` split, a
`*.Build.cs`, and a `Private/Tests/` automation spec, and the linker has been
through them on this box: `libUnrealEditor-V5UrbanHeistCity.so`,
`-V5UrbanStreetTriad.so`, `-V5UrbanOnline.so`, `-V5Heist.so`, `-V5Wanted.so`,
`-V5Honor.so`, `-V5Melee.so`, and `-V5Parkour.so` all sit in
`V5/ue/Binaries/Linux/` next to their sources, built by the `ueagent` user. The
signature math is real domain-specific code — a clamped 0–125 heat curve, a
quadratic five-star payoff, a two-axis Face/Triad ending resolver, a
point-to-segment heist-conflict scan — and each is pinned by UE
`IMPLEMENT_SIMPLE_AUTOMATION_TEST` assertions that check _values_, not
truthiness.
**"Cell" means a mechanic stack composed by thin variant modules.** V5 inverts
V4's layout: the frame-critical verbs live in shared modules, and each playable
sub-ruleset is a content-and-validation module whose `Build.cs` wires the shared
mechanics it needs (`V5UrbanStreetTriad.Build.cs` pulls in `V5Melee` and
`V5Parkour`; `V5UrbanOnline.Build.cs` pulls in `V5Netcode` and
`V5OnlineServices`; `V5UrbanHeistCity.Build.cs` pulls in `V5Wanted`). The honest
consequence is that the variant modules are heavier on **catalog assembly and
`Require(...)` shape-gating over large authored datasets** than on novel
per-frame algorithms — those live one layer down in the shared cores. Both facts
are true at once, and the sections below keep them distinct.
**The data is C++/JSON catalogs; the art is not in-tree.** Consistent with the
rest of V5's 0-binary-`.uasset` accounting, the catalogs that drive these
systems are built in code and validated hard, while the body-shop liveries,
MetaHuman protagonists, environmental-finisher montages, and district meshes
those catalogs reference are _described_ by `FName`/`FSoftObjectPath`, not
cooked. And two honest seams matter here: **`V5Heist` is the
planning-and-classification brain, not the in-world mission** — its
`ResolveEnding` grades an execution-metrics struct that the `V5UrbanHeistCity`
mode must populate during play; the AI-crew spawn-and-drive runtime is not in
that module. Where a claim depends on art or on the in-world runtime, this page
says so.
## The urban-crime experience — what the cell plays like
Strip the sub-rulesets apart and you get two very different cities sharing one
verb library. Heist City is a 140 km² modern sandbox of cars, helicopters, radio
satire, and bank jobs; Street Triad is a 22 km² vertical warren of fistfights,
fire-escape parkour, and a cop who is also a gangster. Both are authored as
validated catalogs and both lean on the same shared melee, parkour, crowd, and
wanted mechanics.
### Heist City — three protagonists, 140 km², twelve heists
`V5UrbanHeistCity` is the GTA-V surface, and its
`UV5_UrbanHeistCity_Catalog::BuildCampaignCatalog`
(`V5/ue/Source/V5UrbanHeistCity/Private/V5UrbanHeistCitySystems.cpp`) is a
validator-enforced content spine. `ValidateCampaignCatalog` refuses anything but
**3 switchable protagonists, 32 main-story missions, 12 main heists, 90
rep-gated side missions, and 16 authored districts** — and it sums the district
areas and demands they total **exactly 140.0 km²**
(`FMath::IsNearlyEqual(Area, 140.0f, 0.01f)`); the sixteen `FDistrictSeed` rows,
from "Downtown Core" (9.0) to "Fort Mesa" military base (17.0), add up to
precisely that. Each of the twelve heists is required to carry **4–6 setup
missions** (the builder seeds `4 + (Index % 3)`) and exactly **three ending
bands** (smooth / hard / catastrophic). The media layer is authored to the same
discipline: **18 in-vehicle radio stations, 140 TV channels, 240 ambient
encounters, and 1,200 talk-radio lines**, each count pinned in
`V5UrbanHeistCityTests.cpp`
(`TestEqual("140 in-world TV channels are authored", …, 140)`).
The signature GTA verb — **multi-protagonist switching** — is data on
`FV5UHCSwitchingConfig`: the validator insists on the Right-D-pad wheel,
simulated downtime for inactive protagonists, the vertical-blade cinematic,
predictive streaming, and a switch transition pinned to **1.5 seconds**
(`SwitchCinematicSeconds == 1.5f`). Beyond the launch map the module also
authors a DLC-gated **Year-1 South Bay** district (a 15 km² World-Partition
addition with 12 rep-tier-4 side missions, validated by
`ValidateYear1NewDistrictExpansion`) and a self-contained **Cyberpunk-2087
sub-cell** (18 missions totalling 1,080 minutes across six vertical
megastructure districts summing to 28 km², seven fixers, twelve cyberware items
— all shape-checked by `ValidateCyberpunkSubCellCatalog`). These are real
authored catalogs with id-drift guards; the playable geometry behind them is
described, not cooked.
### Street Triad — undercover melee and two-axis reputation
`V5UrbanStreetTriad` is the Sleeping-Dogs surface, and it is the more
mechanically opinionated of the two. Its catalog authors **88 missions** — 32
undercover main-story, 18 cop case files, 12 triad favors, 26 ambient encounters
— across a **22 km²** Hong-Kong-equivalent of twelve dense districts (Night
Market, Fish Market, Harbor Rooftops…), with the validator again summing area to
`IsNearlyEqual(Area, 22.0f, 0.01f)`. The defining runtime is the **two-axis
Face/Triad reputation** in `UV5_StreetTriad_Reputation`: `ApplyAction` moves the
two meters independently — `CopCaseComplete` is **+12 Face**, `CivilianHelp`
**+8**, `EscortNPC` **+6**; `TriadCeremony` is **+14 Triad**,
`TriadFavorComplete` **+12**, `WitnessIntimidated` **+6** — each clamped to
`[0,100]`. The campaign's three endings fall out of `ResolveEnding`: a
**Balanced** ending requires _both_ meters ≥ 65 **and** within 10 of each other
(`FMath::Abs(Face − Triad) <= 10`), while a 15-point lead either way routes to
the **Face** or **Triad** branch. The reputation gate is the same predicate the
costume drops and mission availability read (`IsGateUnlocked` →
`Face >= MinFace && Triad >= MinTriad`), so the detective-suit unlocks at Face
45 and the gang-tattoo set at Triad 25, exactly as the seven authored
`FV5STCostumeDropDefinition` rows declare.
Street Triad's hand-to-hand combat is the cell's primary tool, and it composes
the shared **`V5Melee`** module — ten real subsystem files including
`UV5_Melee_RPS` (the Strike < Grapple < Counter < Strike dominance triangle),
`UV5_Melee_ComboMeter`, `UV5_Melee_EnvFinisher`, `UV5_Melee_HitStop`
(`GetHitStopFrames` returns the frame-count "weight" per strike type), and
`UV5_Melee_NPCReaction`. The catalog summary pins **85 base moves, 24
environmental finishers, and 12 weapon pickups**, and traversal composes
**`V5Parkour`** with exactly seven contextual actions (vault, climb, wall-run,
ledge-grab, fire-escape-slide, awning-bounce, roof-jump). The marquee
Sleeping-Dogs verb, **vehicle-to-vehicle hijack**, is a real gated state
machine: `UV5_StreetTriad_VehicleHijack::EvaluateHijack` only sets `bCanAttempt`
when both vehicles exceed 10 m/s, the target is within 4 m, the lane direction
matches, the source is open-top-or-leaning, and the input is held — then a
successful QTE plus free-aim grab yields a **1.8 s** takeover animation, while
any failure throws the protagonist into traffic with a **0.6 s** recovery.
## The bureau / investigation / heist systems
"The Bureau" is two things wearing one name, and both are real code. At the cell
level it is the urban-crime trio of variant modules above. _Underneath_ every
cell it is the **Cross-Continuum Bureau** — the shared wanted, honor, and
progression spine that turns five disparate games into one account, and the
heist-planner brain that the Heist City campaign is built around. The
investigation surface of the urban cell is deliberately lighter than the period
cell's noir procedural — here it is surveillance, lockpicking, and
signal-tracing mini-systems (the `EV5STMiniGameKind` catalog of 24 entries)
feeding a case-board, plus crimes that push into the cross-cell Mind Palace —
and the heavy crime-scene/interrogation verbs are the Period cell's marquee,
detailed in
[../architecture/interrogation-dialogue-and-heist.md](../architecture/interrogation-dialogue-and-heist.md).
```mermaid
flowchart TB
subgraph VAR["Urban-crime variant modules (catalog + validate)"]
HC["V5UrbanHeistCity
3 protags · 32 missions · 12 heists · 16 districts = 140 km²"]
ST["V5UrbanStreetTriad
88 missions · Face/Triad · hijack 1.8s"]
UO["V5UrbanOnline
freeroam 2–30 · 4v4 rollback · 60-route league"]
end
subgraph SHARED["Shared mechanic cores"]
Melee["V5Melee · V5Parkour · V5Crowd"]
Heist["V5Heist
plan · conflict geometry · 3-ending resolver"]
Wanted["V5Wanted
heat→stars · 150×stars² payoff"]
Honor["V5Honor
MoralCompass [-1,1]"]
end
HC --> Heist & Wanted & Melee
ST --> Melee & Wanted & Honor
UO --> Net["V5Netcode · V5OnlineServices"]
Wanted -->|reads bounty| Honor
Honor -->|moral identity ≥0.7 → 1.5× XP| Ledger["FV5BureauXPLedger
tier = TotalXP/2500 + 1"]
Ledger --> Unlocks["cross-cell unlocks
PhotoMode · NG+ · Bureau gear"]
```
### Wanted — heat, stars, and the quadratic payoff
`V5Wanted` is the shared law-response engine, reused by every cell (its
`Build.cs` depends only on `V5Honor`). `UV5_Wanted_Manager::EvaluateStarLevel`
(`V5/ue/Source/V5Wanted/Private/V5WantedSystems.cpp`) maps a `ClampHeat`-bounded
**0–125 heat** onto **0–5 stars** at fixed thresholds **10 / 25 / 45 / 70 /
100**; crimes add heat (a violent crime scales the delta **×1.35**, a vehicle
escape adds a flat **+6**), and sustained police contact escalates via a
per-star rate. The genre-defining detail is that the _response_ is era-scaled —
`EV5WantedResponseEra` routes the spawn plan through frontier (marshals, posse),
hunter (village watch), or sci-fi (faction troopers) variants, while the modern
urban curve unlocks the 1★-visual → 2★-pursuit → 3★-SWAT → 4★-helo → 5★-military
escalation the design promises. Clearing is real: off-radar for 90 seconds, or a
safehouse garage that ticks the timer **3×** faster. And the in-fiction lawyer
payoff is a genuine formula — `CostPaid = max(1, BaseCostPerStar) × Stars²` (150
per star by default) plus your outstanding honor bounty, with a **900-second
cooldown**. The quadratic makes a five-star bribe punishing on purpose: clearing
5★ costs 25× a single star, not 5×.
### Honor and the Cross-Continuum Bureau XP ledger
`V5Honor` is the reputation substrate. Locally it is straightforward — a
`HonorScore` clamped `[−100,100]`, five bands, per-action deltas, and a bounty
by crime type that `V5Wanted` reads back when it prices a payoff. The cross-cell
piece is what makes the Bureau cohere:
`UV5_Honor_KarmaParagonBridge::ComputeMoralCompass` folds **per-cell reputation
inputs** — urban Cop/Triad, period Family/Outsider plus case rating, frontier
honor, hunter humanity, sci-fi Paragon/Renegade — into a single
`LightScore`/`DarkScore` pair and returns a `MoralCompass` clamped `[−1,1]`.
That compass then drives `UV5_Honor_BureauXPMod::GetBureauXPMultiplier`: a
strong moral identity (`|compass| >= 0.7`) earns a **1.5× Bureau-XP
multiplier**, `>= 0.4` earns **1.25×**. Being _someone_ — cleanly heroic or
cleanly ruthless — is mechanically rewarded over fence-sitting. The progression
itself lives in `FV5BureauXPLedger` (`V5/ue/Source/V5Core/Public/V5Types.h`):
`AddXP(EV5Cell, DeltaXP)` accumulates into a per-cell map _and_ a `TotalXP`,
then derives `CurrentTier = max(1, TotalXP/2500 + 1)` and idempotently grants
cross-cell unlocks (Tier 1 PhotoMode, Tier 5 Mind-Palace cross-era pairs, Tier
20 New Game Plus). One honest drift worth flagging: the social-hub persistent
world recomputes tier as `BureauXP/1000 + 1` — a _different divisor_ — so the
hub and the save ledger do not yet agree on tier spacing.
### The heist planner — author, rehearse, classify
`V5Heist` is the urban cell's defining loop, and it is genuinely the planning
and classification brain rather than the in-world job. Each authoring stage has
a real validator: `UV5_Heist_CrewSelection::ValidateCrewSelection` requires
unique ids, **1–4 protagonists**, at least one **Driver**, and at least one
**specialist** (Hacker or Demo); `ValidateVehicleAssignments` demands a
**Getaway** vehicle; and `UV5_Heist_RouteAuthoring::ValidateRoute` insists on
all six waypoint phases (Approach, Entry, InsideTarget, Escape, DumpVehicle,
Safehouse). The rehearsal's value is genuine computational geometry, not a flag:
`UV5_Heist_ConflictDetection::DetectConflicts` computes the true
**point-to-segment distance** from each patrol zone to every route leg and
raises a Red conflict when the zone weight ≥ 0.75. The capstone is
`UV5_Heist_EndingResolver::ResolveEnding`, a strict classifier over an
`FV5HeistExecutionMetrics` struct: a failed escape, any crew loss, or ≤ 10% gain
is **Catastrophic** (cut ×0.25, no follow-up); a clean run with no alarm, no
civilian casualties, and ≥ 95% gain is **Smooth** (cut ×1.15, follow-up
unlocked); everything between is **Hard** (cut clamped to `[0.5, 1.0]` of gain,
follow-up gated at ≥ 35%). Because that metrics struct is populated by the
in-world `V5UrbanHeistCity` mission and not by `V5Heist` itself, the planner is
the honest seam between authored intent and played outcome — the same shape the
architecture companion documents at
[../architecture/interrogation-dialogue-and-heist.md](../architecture/interrogation-dialogue-and-heist.md).
### Urban Online — the GTA-Online surface
`V5UrbanOnline` composes the wanted/heist verbs into the cell's multiplayer
surface, and its `ValidateModeCatalog` pins the shape: a **2–30-player
dedicated-server freeroam** on the shared **300 m Urban AOI profile**; a
**2–4-player role-based heist co-op** on a listen server with AI backfill across
12 maps; a **4v4 rollback deathmatch** at a 60 Hz server tick across **16
maps**; and a **4v4 heist-vs-heist** on dedicated servers. Below the modes sit a
district-driven persistent economy (12 districts × 4 goods = **48** price rows,
each with a demand/supply scalar) and a **60-route speedrun league** on the
90-day live-service season cadence with anti-cheat-clean leaderboards.
Matchmaking and balance writes route through the shared `V5OnlineServices` queue
and balance- ledger contracts, not bespoke endpoints — the same backbone every
cell shares.
## Where this connects
The urban-crime cell is one face of a single game, and it hands off at
well-defined seams:
- **The other narrative city.** The Period-Drama cell shares the wanted curve,
the honor bridge, and the Bureau ledger but spends them on 1947 noir and a
Mafia rank ladder — see [./period-drama-cell.md](./period-drama-cell.md).
- **The shared spine.** The melee, parkour, crowd, perception, netcode, and
Bureau-XP systems every cell sits on are inventoried in
[./shared-cross-cell-systems.md](./shared-cross-cell-systems.md).
- **Architecture companion.** The interrogation, dialogue-wheel, and
heist-planner verbs — including the `V5Heist` validators, conflict geometry,
and ending resolver in prose with line citations — live in
[../architecture/interrogation-dialogue-and-heist.md](../architecture/interrogation-dialogue-and-heist.md),
and the Wanted/Honor/Bureau-ledger spine is detailed in
[../architecture/hunter-period-systems-and-bureau-spine.md](../architecture/hunter-period-systems-and-bureau-spine.md).
- The feature hub: [../V5_features.md](../V5_features.md).