# Factions and reputation (faction.system)

## What it is for

Named factions with a hostility and alliance matrix and a clamped reputation of the player with each faction. They drive who NPCs attack, flee from or ignore; mission reputation rewards and incidents adjust the reputation. With `wanted.police` also installed, this kit alone answers the `faction.relations` service.

## Turn it on

```text
gripforge_gamekit_install   { project_id: "gkp_…", id: "faction.system" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "faction.system",
                              config: { "factions": ["civilian", "police", "gang"], "hostile": [["police", "gang"]], "reputationRange": [-100, 100] } }
```

Needs `npc.core`, `game.engine`; installing the kit brings them along.

## First example

<!-- test: kits/faction_system/tests/faction_system.rs::defaults_declare_three_factions_and_one_hostile_pair -->
With no configuration, three factions exist and only one pair is hostile; the relation is symmetric, a faction is allied with itself, and the other pairs are neutral.

```text
call faction.relations.factions()                  -> ["civilian", "police", "gang"]
call faction.relations.relation("police", "gang")  -> "hostile"
call faction.relations.relation("gang", "police")  -> "hostile"
call faction.relations.relation("civilian", "gang") -> "neutral"
call faction.relations.relation("gang", "gang")    -> "ally"
```

## Settings and defaults

| Setting | Default | Meaning |
|---|---|---|
| `factions` | `["civilian", "police", "gang"]` | Names of the factions (blank and duplicate names are dropped; an empty list falls back on the defaults). |
| `hostile` | `[["police", "gang"]]` | Pairs of mutually hostile factions. |
| `reputationRange` | `[-100, 100]` | Lowest and highest reputation; a reversed range is put in order. |

## Services, events, variables

- Service `faction.relations`: `relation(a, b)` (ally, hostile or neutral), `set(a, b, relation)` (an override that beats the matrix), `hostile(a, b)`, `factions()`, `reputation(faction)`, `adjust(faction, delta, reason)` (returns the new value).
- Verbs and conditions: `adjust_reputation` (`{ "adjust_reputation": { "faction": "villagers", "delta": 10 } }`), `reputation_at_least` (`{ "reputation_at_least": { "faction": "villagers", "value": 20 } }`).
- Events: `faction.reputation` (`faction`, `value`, `delta`, `reason`; `delta` after clamping). It listens to `mission.completed`, `npc.hit`. A hit by the player on an NPC costs 5 reputation with the faction of the victim.
- Variables: `faction.reputation`, `faction.focus` (the faction the reputation variable shows).

## Hooks and modding

| Hook | Meaning |
|---|---|
| `faction.adjust` | The reputation with a faction is about to move by `delta` (a mission reward, the verb, the hit penalty with `reason` npc.hit); `delta` is mutable (a harsher penalty, a doubled reward); cancelled, nothing moves and no event is emitted. |

Moddable: the three settings.

## Limits

Runs as the same Rust logic on the web, in the native player, Godot, Unity and Unreal. The `faction` archetype component stays owned by the engine; this kit only keeps the matrix and the reputations. Reputations are kept in the save.

## Versions

Kit 1.3.0 (the hook in 1.2.0; one kit answers `faction.relations` since 1.3.0); service `faction.relations` 1.0.0. It relies on `npc.behavior` ^1 (from `npc.core`) and `game.engine` ^1; `wanted.police` is optional (mount order only).