Configuration Reference

This page provides a complete reference for all HyperFactions configuration options. For a guide-style walkthrough, see Configuration.

Configuration File Location

mods/com.hyperfactions_HyperFactions/config.json

Configuration Sections

The config is organized into 13 sections:

---

faction

Settings for faction names and member limits.

---

power

Power system settings that govern territory capacity and warfare.

Power Calculations

Regeneration rate examples:

Max claims formula:

maxClaims = min(floor(totalFactionPower / powerPerClaim), claims.maxClaims)

---

claims

Territory claiming rules and restrictions.

World Filtering

World filtering follows these rules:

1. If worldWhitelist is not empty, only listed worlds allow claims
2. If worldWhitelist is empty but worldBlacklist is not, all worlds except listed ones allow claims
3. If both are empty, all worlds allow claims

{
  "claims": {
    "worldWhitelist": ["default", "dungeon_realm"],
    "worldBlacklist": []
  }
}

---

combat

Combat settings including PvP rules and spawn protection.

Spawn Protection (nested)

---

relations

Diplomatic relationship limits.

---

invites

Invitation and join request expiration.

---

stuck

Stuck command settings for escaping enemy territory.

---

teleport

Faction home teleportation settings.

---

updates

Automatic update checking.

---

autoSave

Automatic data saving.

---

messages

Message formatting.

---

gui

GUI settings.

---

territoryNotifications

Territory enter/exit notifications.

---

permissions

Permission system behavior.

---

Default Configuration

This is the complete default configuration file:

{
  "configVersion": 4,
  "faction": {
    "maxMembers": 50,
    "maxMembershipHistory": 10,
    "maxNameLength": 24,
    "minNameLength": 3,
    "allowColors": true
  },
  "power": {
    "maxPlayerPower": 20.0,
    "startingPower": 10.0,
    "powerPerClaim": 2.0,
    "deathPenalty": 1.0,
    "killReward": 0.0,
    "regenPerMinute": 0.1,
    "regenWhenOffline": false
  },
  "claims": {
    "maxClaims": 100,
    "onlyAdjacent": false,
    "decayEnabled": true,
    "decayDaysInactive": 30,
    "preventDisconnect": false,
    "worldWhitelist": [],
    "worldBlacklist": []
  },
  "combat": {
    "tagDurationSeconds": 15,
    "allyDamage": false,
    "factionDamage": false,
    "taggedLogoutPenalty": true,
    "logoutPowerLoss": 1.0,
    "neutralAttackPenalty": 0.0,
    "spawnProtection": {
      "enabled": true,
      "durationSeconds": 5,
      "breakOnAttack": true,
      "breakOnMove": true
    }
  },
  "relations": {
    "maxAllies": 10,
    "maxEnemies": -1
  },
  "invites": {
    "inviteExpirationMinutes": 5,
    "joinRequestExpirationHours": 24
  },
  "stuck": {
    "warmupSeconds": 30,
    "cooldownSeconds": 300
  },
  "teleport": {
    "warmupSeconds": 5,
    "cooldownSeconds": 300,
    "cancelOnMove": true,
    "cancelOnDamage": true
  },
  "updates": {
    "enabled": true,
    "url": "https://api.github.com/repos/ZenithDevHQ/HyperFactions/releases/latest",
    "releaseChannel": "stable"
  },
  "autoSave": {
    "enabled": true,
    "intervalMinutes": 5
  },
  "messages": {
    "prefixText": "HyperFactions",
    "prefixColor": "#55FFFF",
    "prefixBracketColor": "#AAAAAA",
    "primaryColor": "#00FFFF"
  },
  "gui": {
    "title": "HyperFactions",
    "terrainMapEnabled": true
  },
  "territoryNotifications": {
    "enabled": true
  },
  "permissions": {
    "adminRequiresOp": true,
    "allowWithoutPermissionMod": false
  }
}

Configuration Profiles

PvP-Focused Server

High-stakes combat with meaningful consequences:

{
  "power": {
    "maxPlayerPower": 15,
    "startingPower": 10,
    "deathPenalty": 2.0,
    "regenPerMinute": 0.15,
    "powerPerClaim": 1.5
  },
  "combat": {
    "tagDurationSeconds": 20,
    "taggedLogoutPenalty": true,
    "logoutPowerLoss": 2.0
  },
  "relations": {
    "maxAllies": 3,
    "maxEnemies": -1
  }
}

Casual/Building Server

Relaxed settings for creative communities:

{
  "power": {
    "maxPlayerPower": 50,
    "startingPower": 25,
    "deathPenalty": 0,
    "regenPerMinute": 0.05,
    "powerPerClaim": 5
  },
  "combat": {
    "tagDurationSeconds": 0,
    "factionDamage": false,
    "allyDamage": false
  },
  "relations": {
    "maxAllies": -1,
    "maxEnemies": 0
  }
}

Roleplay Server

Balanced settings encouraging diplomacy:

{
  "power": {
    "maxPlayerPower": 30,
    "startingPower": 15,
    "deathPenalty": 0.5,
    "regenPerMinute": 0.1,
    "powerPerClaim": 3
  },
  "relations": {
    "maxAllies": 5,
    "maxEnemies": 5
  },
  "claims": {
    "onlyAdjacent": true,
    "decayDaysInactive": 14
  }
}

---

Module Configuration Files

In addition to the main config.json, HyperFactions uses module configuration files stored in the config/ subdirectory. Each module can be enabled/disabled independently.

mods/com.hyperfactions_HyperFactions/
├── config.json                       ← Main configuration (documented above)
└── config/
    ├── announcements.json            ← Announcement system settings
    ├── backup.json                   ← Backup system settings
    ├── chat.json                     ← Chat formatting and relation colors
    ├── debug.json                    ← Debug logging options
    ├── economy.json                  ← Economy integration
    ├── faction-permissions.json      ← Default territory permissions
    ├── gravestones.json              ← Gravestone integration settings
    └── worldmap.json                 ← World map settings

---

Related Topics

• Configuration Guide - Walkthrough and examples
• Power System - Power mechanics explained
• Permissions - Permission nodes
• Admin Commands - Reload command