Documentation/content/gameplay-systems/reputation.en.md

---
title: Reputation
type: docs
weight: 7
---

The reputation system provides faction standing mechanics that affect NPC behavior and interactions.

**Package:** `com.hypixel.hytale.builtin.adventure.reputation`

## Architecture

```
ReputationPlugin
├── Assets
│   ├── ReputationGroup - Faction definitions
│   └── ReputationRank - Standing level definitions
├── Components
│   └── ReputationGroupComponent - NPC faction assignment
├── Storage
│   ├── ReputationDataResource - World-level storage
│   └── PlayerConfigData - Player-level storage
├── Requirements
│   └── ReputationRequirement - Choice requirement
├── Configuration
│   └── ReputationGameplayConfig
└── Commands
    └── ReputationCommand (value, set, add, rank)
```

## Reputation Groups

Factions are defined as `ReputationGroup` assets:

```java
public class ReputationGroup implements JsonAssetWithMap<String, DefaultAssetMap<String, ReputationGroup>> {
    protected String id;
    protected String[] npcGroups;           // NPC groups in this faction
    protected int initialReputationValue;    // Starting reputation
}
```

**Asset Location:** `NPC/Reputation/Groups/`

### Group Configuration

```yaml
# NPC/Reputation/Groups/village_faction.json
{
  "Id": "village_faction",
  "NPCGroups": ["villagers", "guards"],
  "InitialReputationValue": 0
}
```

## Reputation Ranks

Standing levels defined as `ReputationRank` assets:

```java
public class ReputationRank implements JsonAssetWithMap<String, DefaultAssetMap<String, ReputationRank>> {
    protected String id;
    protected int minValue;
    protected int maxValue;
    protected Attitude attitude;  // NPC attitude at this rank
}
```

**Asset Location:** `NPC/Reputation/Ranks/`

### Rank Configuration

```yaml
# NPC/Reputation/Ranks/friendly.json
{
  "Id": "friendly",
  "MinValue": 50,
  "MaxValue": 100,
  "Attitude": "friendly"
}
```

## Storage Modes

Reputation can be stored per-player or per-world:

```java
public enum ReputationStorageType {
    PerPlayer,  // Each player has own reputation
    PerWorld    // Shared world reputation
}
```

### Per-Player Storage

```java
PlayerConfigData playerConfigData = player.getPlayerConfigData();
Object2IntMap<String> reputationData = playerConfigData.getReputationData();
```

### Per-World Storage

```java
ReputationDataResource resource = world.getEntityStore().getStore()
    .getResource(ReputationPlugin.get().getReputationDataResourceType());
Object2IntMap<String> worldReputation = resource.getReputationStats();
```

## NPC Faction Assignment

### ReputationGroupComponent

Assigns NPCs to factions:

```java
ComponentType<EntityStore, ReputationGroupComponent> type =
    ReputationPlugin.get().getReputationGroupComponentType();

ReputationGroupComponent comp = store.getComponent(npcRef, type);
String factionId = comp.getReputationGroupId();
```

## API Usage

### Changing Reputation

```java
ReputationPlugin rep = ReputationPlugin.get();

// Change reputation with faction (returns new value)
int newValue = rep.changeReputation(player, "village_faction", 10, componentAccessor);

// Change reputation via NPC reference
int newValue = rep.changeReputation(player, npcRef, -5, componentAccessor);

// World-level reputation change
int newValue = rep.changeReputation(world, "village_faction", 15);
```

### Getting Reputation

```java
// Get reputation value
int value = rep.getReputationValue(store, playerRef, "village_faction");
int value = rep.getReputationValue(store, playerRef, npcRef);

// Get reputation rank
ReputationRank rank = rep.getReputationRank(store, playerRef, "village_faction");
ReputationRank rank = rep.getReputationRankFromValue(value);

// Get NPC attitude based on reputation
Attitude attitude = rep.getAttitude(store, playerRef, npcRef);
```

## Choice Requirements

Use reputation as requirement for dialogue choices:

```java
ChoiceRequirement.CODEC.register(
    "Reputation",
    ReputationRequirement.class,
    ReputationRequirement.CODEC
);
```

### Choice Configuration

```yaml
{
  "Type": "Reputation",
  "FactionId": "village_faction",
  "MinRank": "friendly"
}
```

## Commands

| Command | Description |
|---------|-------------|
| `/reputation` | Base reputation command |
| `/reputation value <faction> [player]` | Show reputation value |
| `/reputation set <faction> <value> [player]` | Set reputation |
| `/reputation add <faction> <amount> [player]` | Add reputation |
| `/reputation rank <faction> [player]` | Show current rank |

## Configuration

### Gameplay Config

```java
public class ReputationGameplayConfig {
    ReputationStorageType reputationStorageType;

    public static ReputationGameplayConfig getOrDefault(GameplayConfig config);
}
```

```yaml
# gameplay_config.json
{
  "Reputation": {
    "ReputationStorageType": "PerPlayer"
  }
}
```

## Related Plugins

### ObjectiveReputationPlugin

Rewards reputation on objective completion:

```java
public class ReputationCompletion implements ObjectiveCompletion {
    // Awards reputation when objective completes
}
```

### NPCReputationPlugin

NPC attitude based on reputation:

```java
public class ReputationAttitudeSystem {
    // Updates NPC attitude based on player reputation
}
```

### ShopReputationPlugin

Reputation-gated shop items.

## Validation

Ranks are validated on plugin start:

```java
// Warns if gaps between rank ranges
// Warns if rank ranges overlap
```