Configuration

Learn how to configure HyperPerms for your server. This guide covers all configuration options and their effects.

Configuration File

The main configuration file is located at plugins/HyperPerms/config.json. HyperPerms uses JSON format for all configuration files and automatically creates the config with sensible defaults on first run.

Full Configuration Reference

Here's the complete configuration file with all available options:

json

{
  "storage": {
    "type": "json",
    "json": {
      "directory": "data",
      "prettyPrint": true
    },
    "sqlite": {
      "file": "hyperperms.db"
    },
    "mysql": {
      "host": "localhost",
      "port": 3306,
      "database": "hyperperms",
      "username": "root",
      "password": "",
      "poolSize": 10
    }
  },
  "cache": {
    "enabled": true,
    "expirySeconds": 300,
    "maxSize": 10000
  },
  "chat": {
    "enabled": true,
    "format": "%prefix%%player%%suffix%&8: &f%message%",
    "allowPlayerColors": true,
    "colorPermission": "hyperperms.chat.color"
  },
  "backup": {
    "autoBackup": true,
    "maxBackups": 10,
    "backupOnSave": false,
    "intervalSeconds": 3600
  },
  "defaults": {
    "group": "default",
    "createDefaultGroup": true,
    "prefix": "&7",
    "suffix": ""
  },
  "tasks": {
    "expiryCheckIntervalSeconds": 60,
    "autoSaveIntervalSeconds": 300
  },
  "verbose": {
    "enabledByDefault": false,
    "logToConsole": true
  },
  "server": {
    "name": ""
  },
  "webEditor": {
    "url": "https://www.hyperperms.com",
    "timeoutSeconds": 10
  }
}

Configuration Sections

Storage Settings

json

"storage": {
  "type": "json",
  "json": {
    "directory": "data",
    "prettyPrint": true
  },
  "sqlite": {
    "file": "hyperperms.db"
  },
  "mysql": {
    "host": "localhost",
    "port": 3306,
    "database": "hyperperms",
    "username": "root",
    "password": "",
    "poolSize": 10
  }
}

type - Storage backend: json, sqlite, or mysql
json.directory - Directory for JSON data files (default: "data")
json.prettyPrint - Format JSON files for readability
sqlite.file - SQLite database filename
mysql.* - MySQL connection settings for larger servers

JSON storage works well for most servers. Use SQLite or MySQL for larger servers with many players or when you need database-level reliability.

Cache Settings

json

"cache": {
  "enabled": true,
  "expirySeconds": 300,
  "maxSize": 10000
}

enabled - Enable permission result caching for performance
expirySeconds - How long cached results are valid (default: 5 minutes)
maxSize - Maximum number of cached permission results

Keep caching enabled for best performance. The cache is automatically invalidated when permissions change.

Chat Format Settings

json

"chat": {
  "enabled": true,
  "format": "%prefix%%player%%suffix%&8: &f%message%",
  "allowPlayerColors": true,
  "colorPermission": "hyperperms.chat.color"
}

enabled - Enable HyperPerms chat formatting
format - Chat message format template
allowPlayerColors - Allow players to use color codes in chat
colorPermission - Permission required to use colors in chat

Available format placeholders:

Placeholder	Description
%player%	Player's display name
%playername%	Player's actual username
%uuid%	Player's UUID
%prefix%	Resolved prefix (see priority below)
%suffix%	Resolved suffix (see priority below)
%group%	Primary group name
%primarygroup%	Primary group name (alias)
%groups%	Comma-separated list of all groups
%message%	The chat message content
%world%	Current world name
%server%	Server name from config
%online%	Online player count
%maxplayers%	Maximum player capacity

Backup Settings

json

"backup": {
  "autoBackup": true,
  "maxBackups": 10,
  "backupOnSave": false,
  "intervalSeconds": 3600
}

autoBackup - Enable automatic periodic backups
maxBackups - Maximum number of backups to keep (oldest deleted first)
backupOnSave - Create a backup every time data is saved
intervalSeconds - Time between automatic backups (default: 1 hour)

Default Settings

json

"defaults": {
  "group": "default",
  "createDefaultGroup": true,
  "prefix": "&7",
  "suffix": ""
}

group - The default group for new players
createDefaultGroup - Automatically create the default group if it doesn't exist
prefix - Default prefix for players without one (fallback)
suffix - Default suffix for players without one (fallback)

Task Settings

json

"tasks": {
  "expiryCheckIntervalSeconds": 60,
  "autoSaveIntervalSeconds": 300
}

expiryCheckIntervalSeconds - How often to check for expired permissions
autoSaveIntervalSeconds - Auto-save interval (default: 5 minutes)

Verbose/Debug Settings

json

"verbose": {
  "enabledByDefault": false,
  "logToConsole": true
}

enabledByDefault - Enable verbose mode on startup (for debugging)
logToConsole - Log verbose output to server console

Verbose mode logs every permission check and can generate significant output. Only enable for debugging purposes.

Server Settings

json

"server": {
  "name": ""
}

name - Server identifier for multi-server networks (used in context matching)

Web Editor Settings

json

"webEditor": {
  "url": "https://www.hyperperms.com",
  "timeoutSeconds": 10
}

url - URL of the web editor (default is the official HyperPerms editor)
timeoutSeconds - API timeout for web editor communication

The web editor at hyperperms.com provides a visual interface for managing permissions. If you're self-hosting, update the URL to your instance. See the self-hosting guide.

Reloading Configuration

After making changes to the configuration file, reload HyperPerms without restarting your server:

text

/hp reload

Some settings (like storage type) require a full server restart to take effect.

Example Configurations

Small Server (Under 50 Players)

json

{
  "storage": {
    "type": "json",
    "json": {
      "directory": "data",
      "prettyPrint": true
    }
  },
  "cache": {
    "enabled": true,
    "expirySeconds": 300,
    "maxSize": 1000
  },
  "backup": {
    "autoBackup": true,
    "maxBackups": 10,
    "intervalSeconds": 3600
  }
}

Large Server (100+ Players)

json

{
  "storage": {
    "type": "mysql",
    "mysql": {
      "host": "localhost",
      "port": 3306,
      "database": "hyperperms",
      "username": "perms_user",
      "password": "secure_password",
      "poolSize": 15
    }
  },
  "cache": {
    "enabled": true,
    "expirySeconds": 600,
    "maxSize": 50000
  },
  "backup": {
    "autoBackup": true,
    "maxBackups": 48,
    "intervalSeconds": 1800
  },
  "tasks": {
    "expiryCheckIntervalSeconds": 30,
    "autoSaveIntervalSeconds": 120
  }
}

Next Steps

First Setup - Create your first groups and permissions
Storage Configuration - Deep dive into storage options
Self-Hosting the Web Editor - Run your own editor instance

Have questions or found an issue with the documentation?

Send us feedback →