Factions

Usage guide of faction.system: named factions, a hostility and alliance matrix, the clamped reputation of the player, settings and defaults, the faction.relations service, events, verbs and the faction.adjust hook.

Source: module-kits:kits/faction_system/usage/en.mdView Markdown source

Also read offline — CLI: grip-forge docs faction-systemMCP tool: gripforge_docs { "topic": "faction-system" }

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 #

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 #

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.

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).