Reputation System

The reputation system tracks player standing with NPCs and factions. Reputation unlocks ranks, triggers reward actions, and gates quest availability. <span class="since-badge">v2.5.0</span>

Overview

Per-player — Each player has independent reputation values
Per-NPC / Per-Faction — Reputation is tracked separately for each NPC or faction
Never decreases — Reputation only goes up (unless explicitly removed via action)
Rank thresholds — When reputation crosses a rank threshold, a reward action fires automatically
Quest gating — Quests can require minimum reputation to become available

Configuration

Reputation is defined in config/reputation.json within your quest pack:

{
  "npcs": {
    "yourmod:innkeeper": {
      "titleLangKey": "yourmod:reputation-npc-innkeeper-title",
      "ranks": [
        { "min": 0, "rankLangKey": "yourmod:reputation-innkeeper-rank-0" },
        { "min": 500, "rankLangKey": "yourmod:reputation-innkeeper-rank-500", "rewardAction": "giveitem game:redmeat-cured 6" },
        { "min": 1000, "rankLangKey": "yourmod:reputation-innkeeper-rank-1000", "rewardAction": "giveitem game:redmeat-vintage 8" },
        { "min": 2000, "rankLangKey": "yourmod:reputation-innkeeper-rank-2000", "rewardAction": "questitem yourmod:special-reward" }
      ]
    }
  },
  "factions": {
    "yourmod:guild": {
      "titleLangKey": "yourmod:reputation-faction-guild-title",
      "ranks": [
        { "min": 0, "rankLangKey": "yourmod:reputation-guild-rank-0" },
        { "min": 100, "rankLangKey": "yourmod:reputation-guild-rank-100" },
        { "min": 500, "rankLangKey": "yourmod:reputation-guild-rank-500" }
      ]
    }
  }
}

Config Fields

Field	Type	Description
`npcs`	object	Map of NPC reputation definitions (key = NPC ID)
`factions`	object	Map of faction reputation definitions (key = faction ID)
`titleLangKey`	string	Localization key for the reputation title shown in UI
`ranks`	array	Ordered array of rank thresholds
`ranks[].min`	int	Minimum reputation to reach this rank
`ranks[].rankLangKey`	string	Localization key for the rank name
`ranks[].rewardAction`	string	Action string executed when the player first reaches this rank (optional)

Scopes

Reputation has two scopes:

Scope	Description	Use Case
`npc`	Tied to a specific NPC entity	Personal relationship with a quest giver
`faction`	Shared across all NPCs in a faction	Guild standing, territory control

Adding Reputation

Use the addreputation action in quests, dialogues, or stage completions:

{
  "id": "addreputation",
  "args": ["npc", "yourmod:innkeeper", "50"]
}

Arguments:

Index	Description
`args[0]`	Scope: `npc` or `faction`
`args[1]`	The NPC or faction identifier
`args[2]`	Amount to add (positive) or subtract (negative)
`args[3]`	Maximum reputation cap (optional)
`args[4]`	Once-key — ensures this reputation is only granted once (optional)

Action string format

addreputation npc 'yourmod:innkeeper' 50
addreputation faction 'yourmod:guild' 100 500 'quest-complete-bonus'

Rank Rewards

When a player's reputation crosses a rank's min threshold for the first time, the rewardAction string is executed. This is a one-time reward per rank per player.

{
  "min": 500,
  "rankLangKey": "yourmod:reputation-rank-trusted",
  "rewardAction": "questitem yourmod:trusted-badge; playsound 'game:sounds/effect/receptionbell' 0.5; notify 'yourmod:rank-up-trusted'"
}

Common reward actions:

questitem — Give a unique item
giveitem — Give vanilla items
playsound — Play a sound effect
notify — Show a notification
addjournalentry — Add a journal entry

Quest Gating

Quests can require minimum reputation to become available. Set reputationRequirements in the quest definition:

{
  "id": "yourmod:advanced-quest",
  "reputationRequirements": [
    { "scope": "npc", "id": "yourmod:innkeeper", "min": 500 }
  ]
}

The quest will only appear in the quest giver's menu once the player meets all reputation requirements.

Quest Giver Integration

Link a quest giver NPC to a reputation ID using the reputationnpc field in the questgiver behavior:

{
  "code": "questgiver",
  "quests": ["yourmod:quest1", "yourmod:quest2"],
  "reputationnpc": "yourmod:innkeeper"
}

This displays the player's current reputation and rank in the quest selection UI.

UI Display

The quest giver dialog shows:

Current reputation value
Current rank name
Progress bar to next rank
Rank-up notification when a threshold is crossed

Hollow Trials Reputation

Hollow Trials uses its own reputation track (see Hollow Trials). Trial reputation:

Is earned from boss kills and challenge completions
Gates tier access (T2 requires 100, T3 requires 300)
Unlocks Trial Shop items

Reputation Flow

graph TD
    A[Player completes quest
or action grants rep] --> B[AddReputation called]
    B --> C{New rank reached?}
    C -->|Yes| D[Execute rewardAction]
    D --> E[Show rank-up notification]
    C -->|No| F[Update UI progress bar]
    E --> F
    F --> G[Sync to database
if configured]

Complete Example

Multi-rank NPC with rewards

{
  "npcs": {
    "yourmod:blacksmith": {
      "titleLangKey": "yourmod:reputation-npc-blacksmith",
      "ranks": [
        { "min": 0, "rankLangKey": "yourmod:rep-blacksmith-stranger" },
        { "min": 100, "rankLangKey": "yourmod:rep-blacksmith-acquaintance", "rewardAction": "giveitem game:metal-nuggets 10" },
        { "min": 300, "rankLangKey": "yourmod:rep-blacksmith-customer", "rewardAction": "giveitem game:gear-rusty 2" },
        { "min": 600, "rankLangKey": "yourmod:rep-blacksmith-friend", "rewardAction": "questitem yourmod:blacksmith-friend-badge" },
        { "min": 1000, "rankLangKey": "yourmod:rep-blacksmith-partner", "rewardAction": "giveitem game:gear-temporalsteel 5; notify 'yourmod:rep-blacksmith-partner-reward'" }
      ]
    }
  },
  "factions": {
    "yourmod:merchant-guild": {
      "titleLangKey": "yourmod:reputation-faction-merchant-guild",
      "ranks": [
        { "min": 0, "rankLangKey": "yourmod:rep-guild-outsider" },
        { "min": 250, "rankLangKey": "yourmod:rep-guild-associate" },
        { "min": 500, "rankLangKey": "yourmod:rep-guild-member" },
        { "min": 1000, "rankLangKey": "yourmod:rep-guild-elite" }
      ]
    }
  }
}

Quest with reputation gate

{
  "id": "yourmod:masterwork-order",
  "reputationRequirements": [
    { "scope": "npc", "id": "yourmod:blacksmith", "min": 600 }
  ],
  "stages": [
    {
      "name": "Forge the blade",
      "objectives": [
        { "id": "craftitem", "args": ["game:blade-masterwork", "1", "false", "true"] }
      ]
    }
  ],
  "actionRewards": [
    { "id": "addreputation", "args": ["npc", "yourmod:blacksmith", "150", "1000", "masterwork-order"] }
  ]
}

C# API <span class="since-badge">v3.0.0</span>

// Get current reputation
int rep = questSystem.ReputationManager.GetReputation(player, "npcId");

// Add reputation (with optional max and once-key)
questSystem.ReputationManager.AddReputation(player, "npc", "npcId", 50, max: 1000, onceKey: "quest1");

// Get current rank
ReputationRank rank = questSystem.ReputationManager.GetCurrentRank(player, "npcId");

// Check if player meets requirements
bool meets = questSystem.ReputationManager.MeetsRequirements(player, new[] {
    new ReputationRequirement { scope = "npc", id = "yourmod:innkeeper", min = 500 }
});

Localization

{
  "yourmod:reputation-npc-innkeeper-title": "Innkeeper",
  "yourmod:reputation-innkeeper-rank-0": "Stranger",
  "yourmod:reputation-innkeeper-rank-500": "Regular",
  "yourmod:reputation-innkeeper-rank-1000": "Trusted",
  "yourmod:reputation-innkeeper-rank-2000": "Family"
}