Configuration

HyperFactions is highly configurable. This guide explains the key configuration options for getting started.

Configuration Files

HyperFactions uses multiple configuration files:

mods/com.hyperfactions_HyperFactions/
├── config.json               ← Main configuration (covered in this guide)
└── config/                   ← Module configurations
    ├── announcements.json    ← Announcement settings
    ├── backup.json           ← Backup system settings
    ├── chat.json             ← Chat formatting
    ├── debug.json            ← Debug logging
    ├── economy.json          ← Economy/treasury settings
    ├── faction-permissions.json  ← Default territory permissions
    ├── gravestones.json      ← Gravestone integration settings
    └── worldmap.json         ← World map display settings

The main config.json covers faction limits, power, claims, combat, relations, and more. Module configs in the config/ subdirectory handle specialized features like economy, chat, map display, and backups.

Essential Settings

These are the most important settings to configure for your server.

Faction Limits

Power System

The power system is the core of HyperFactions. These settings affect how factions claim and defend territory:

Territory Claims

Combat Settings

Spawn Protection

Diplomatic Relations

Server Type Configurations

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
  }
}

Effects:

• Lower max power = smaller empires
• Higher death penalty = wars matter more
• Faster regen = quicker recovery
• Limited allies = more conflict

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
  }
}

Effects:

• No combat penalties
• Large territory for builders
• No PvP consequences
• Unlimited friends, no enemies

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
  }
}

Effects:

• Moderate power economy
• Limited diplomacy encourages RP
• Connected territories required
• Faster decay removes abandoned areas

Teleportation Settings

Configure faction home teleportation:

For the /f stuck command:

Automatic Features

Auto-Save

Update Checking

Permission Behavior

When no permission manager (HyperPerms/LuckPerms) is installed:

World Filtering

Control which worlds allow faction claims:

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

Rules:

1. If worldWhitelist is not empty, only listed worlds allow claims
2. If empty, worldBlacklist blocks specific worlds
3. If both empty, all worlds allow claims

Message Customization

Economy Settings

If VaultUnlocked is installed, configure the faction treasury:

See Economy for how the treasury system works.

World Map Settings

Configure the interactive territory map:

Map display options are configured in config/worldmap.json:

Next Steps

Now that you've configured HyperFactions:

1. Set up permissions if using HyperPerms or LuckPerms
2. Create zones for spawn and arenas
3. Test your config by creating a faction
4. See the Configuration Reference for all options

Related Topics

• Configuration Reference - Complete option list
• Power System - Power mechanics
• Zones - SafeZone and WarZone setup
• Admin Commands - Reload and debug