Police wanted level in your game (wanted.police) #

What it is for #

wanted.police keeps the police wanted level of an open-world game: the variable wanted.level, from 0 to maxLevel. The level rises when the player drives a stolen vehicle, enters a police zone while wanted, or runs over a civilian with their vehicle. It drops by one after decaySeconds without any officer seeing the player. For each level the kit keeps a number of officers alive (and a police car from level 2), who chase the player and arrest them when close and slow. The kit has no display module: the officers and the car use the models you bind, or capsules and a placeholder car until then. It also serves a small faction.relations matrix (police, civilians, player).

Turn it on #

gripforge_gamekit_install   { project_id: "gkp_…", id: "wanted.police" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "wanted.police",
                              config: { "maxLevel": 3, "decaySeconds": 20, "spawnPerLevel": [0, 1, 2, 3] } }

It requires npc.behavior, npc.perception (from npc.core), vehicle.enter (from vehicle.enter_exit), world.zones and game.engine. Tag the zones that count as police zones police (or police_zone). Officers come from the npcs document with faction: "police" (a built-in one is used if there is none). Without npc.behavior there are no officers and the game is told.

First example #

<!-- test: kits/wanted_police/tests/wanted_police.rs::add_set_and_clear_move_the_level_within_bounds_and_say_why --> The level is moved with the service, always inside 0..maxLevel, and every change says why:

wanted.level.add(1)                 // 1, wanted.changed { level: 1, previous: 0, reason: "heat", max: 3 }
wanted.level.raise(5, "riot")       // 3, held to the maximum, reason "riot"
wanted.level.set(2)                 // 2, reason "set"
wanted.level.clear("amnesty")       // 0, wanted.changed then wanted.cleared

Settings and defaults #

Officers appear between 30 and 45 m from the player. A scene can override heat, spawnPerLevel and decaySeconds.

Services, events, variables #

• wanted.level (service): add(n, reason?), raise(n, reason?), set(n, reason?), clear(reason?), police() (the officers alive, chasing or arresting), max(). Levels are clamped; a nonsense value is level 0.
• faction.relations (service): relation(a, b) (ally, neutral or hostile), hostile(a, b), set(a, b, relation). The player and the police are hostile while the player is wanted.
• Events: wanted.changed (level, previous, reason, max; reason is stolenVehicle, enterPoliceZone, hitPedestrian, decay, arrested, var for a write of the variable from elsewhere, or the caller's), wanted.cleared, police.arrested (entity, by).
• Variable: wanted.level (guarded: a write from elsewhere is clamped and announced, and asks the hooks first).
• Content: action set_wanted, condition wanted_at_least, NPC behaviours chase and arrest.

Hooks and modding #

All the settings above are moddable.

When it does not do what you expect #

• No officers come: spawnPerLevel is 0 at that level, npc.behavior is missing, or a police.dispatch tap cancelled.
• The level never goes down: an officer still sees the player, or a wanted.lower tap cancels.
• Entering a zone adds nothing: the zone is not tagged police, or the player is not wanted yet.
• Officers are capsules: bind a rigged police_officer character asset; the car is the police_car asset.

Limits #

Heat comes from three sources only; other crimes call wanted.level.raise. The arrest holds a slow player within 2.5 m for 2 seconds.

Versions #

Kit version 1.5.0 (the guarded variable and the four hooks).