Configuration Reference

This page provides a complete reference for all 47 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 14 sections with 47 total options:

---

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.

---

worldMap

World map integration.

---

permissions

Permission system behavior.

---

Default Configuration

This is the complete default configuration file:

{
  "configVersion": 2,
  "faction": {
    "maxMembers": 50,
    "maxNameLength": 24,
    "minNameLength": 3,
    "allowColors": true
  },
  "power": {
    "maxPlayerPower": 20.0,
    "startingPower": 10.0,
    "powerPerClaim": 2.0,
    "deathPenalty": 1.0,
    "regenPerMinute": 0.1,
    "regenWhenOffline": false
  },
  "claims": {
    "maxClaims": 100,
    "onlyAdjacent": false,
    "decayEnabled": true,
    "decayDaysInactive": 30,
    "worldWhitelist": [],
    "worldBlacklist": []
  },
  "combat": {
    "tagDurationSeconds": 15,
    "allyDamage": false,
    "factionDamage": false,
    "taggedLogoutPenalty": true,
    "logoutPowerLoss": 1.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": {
    "prefix": "\u00A7b[HyperFactions]\u00A7r ",
    "primaryColor": "#00FFFF"
  },
  "gui": {
    "title": "HyperFactions"
  },
  "territoryNotifications": {
    "enabled": true
  },
  "worldMap": {
    "enabled": true
  },
  "permissions": {
    "adminRequiresOp": true,
    "fallbackBehavior": "deny"
  }
}

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.

Configuration File Structure

mods/com.hyperfactions_HyperFactions/
├── config.json                       ← Main configuration (documented above)
└── config/
    ├── 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

---

config/backup.json

Controls the automatic backup system using GFS (Grandfather-Father-Son) rotation.

{
  "enabled": true,
  "hourlyRetention": 24,
  "dailyRetention": 7,
  "weeklyRetention": 4,
  "manualRetention": 10,
  "onShutdown": true
}

---

config/chat.json

Controls how faction tags appear in chat and relation-based color coding.

Format templates:

• format uses placeholders for chat message formatting
• tagFormat uses the tag placeholder for the faction tag display

Available placeholders: faction_tag, prefix, player, suffix, message, tag (wrap in curly braces)

{
  "enabled": true,
  "format": "{faction_tag}{prefix}{player}{suffix}: {message}",
  "tagDisplay": "tag",
  "tagFormat": "[{tag}] ",
  "noFactionTag": "",
  "priority": "LATE",
  "relationColors": {
    "own": "#00FF00",
    "ally": "#FF69B4",
    "neutral": "#AAAAAA",
    "enemy": "#FF0000"
  }
}

---

config/debug.json

Controls debug logging output by category.

{
  "enabled": false,
  "enabledByDefault": false,
  "logToConsole": true,
  "categories": {
    "power": false,
    "claim": false,
    "combat": false,
    "protection": false,
    "relation": false,
    "territory": false
  }
}

---

config/economy.json

Controls faction economy integration (for future economy features).

{
  "enabled": true,
  "currencyName": "dollar",
  "currencyNamePlural": "dollars",
  "currencySymbol": "$",
  "startingBalance": 0.0
}

---

config/faction-permissions.json

Controls default territory permissions for new factions and server-enforced permission locks.

Structure:

• defaults - Default permissions for new factions
• locks - Which permissions factions cannot change
• forced - Values to use when a permission is locked

{
  "enabled": true,
  "defaults": {
    "outsiderBreak": false,
    "outsiderPlace": false,
    "outsiderInteract": false,
    "allyBreak": false,
    "allyPlace": false,
    "allyInteract": true,
    "memberBreak": true,
    "memberPlace": true,
    "memberInteract": true,
    "pvpEnabled": true,
    "officersCanEdit": false
  },
  "locks": {
    "outsiderBreak": false,
    "outsiderPlace": false,
    "outsiderInteract": false,
    "allyBreak": false,
    "allyPlace": false,
    "allyInteract": false,
    "memberBreak": false,
    "memberPlace": false,
    "memberInteract": false,
    "pvpEnabled": false,
    "officersCanEdit": false
  },
  "forced": {
    "outsiderBreak": false,
    "outsiderPlace": false,
    "outsiderInteract": false,
    "allyBreak": false,
    "allyPlace": false,
    "allyInteract": true,
    "memberBreak": true,
    "memberPlace": true,
    "memberInteract": true,
    "pvpEnabled": true,
    "officersCanEdit": false
  }
}

---

Related Topics

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