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

title, type, weight

title	type	weight
Reputation	docs	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:

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

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

Reputation Ranks

Standing levels defined as ReputationRank assets:

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

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

Storage Modes

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

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

Per-Player Storage

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

Per-World Storage

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

NPC Faction Assignment

ReputationGroupComponent

Assigns NPCs to factions:

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

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

API Usage

Changing Reputation

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

// 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:

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

Choice Configuration

{
  "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

public class ReputationGameplayConfig {
    ReputationStorageType reputationStorageType;

    public static ReputationGameplayConfig getOrDefault(GameplayConfig config);
}

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

Related Plugins

ObjectiveReputationPlugin

Rewards reputation on objective completion:

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

NPCReputationPlugin

NPC attitude based on reputation:

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

ShopReputationPlugin

Reputation-gated shop items.

Validation

Ranks are validated on plugin start:

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