Init

content/gameplay-systems/reputation.en.md

@@ -0,0 +1,241 @@
+---
+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
+```