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.

Full Configuration Reference

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

json

{
  "server": {
    "name": "My Hytale Server",
    "syncInterval": 300
  },
  "storage": {
    "type": "json",
    "autoSave": true,
    "autoSaveInterval": 300,
    "backups": {
      "enabled": true,
      "interval": 3600,
      "maxBackups": 24
    }
  },
  "webEditor": {
    "enabled": true,
    "url": "https://hyperperms.dev/editor",
    "sessionTimeout": 86400
  },
  "defaults": {
    "group": "default",
    "applyDefaultGroup": true
  },
  "contexts": {
    "world": true,
    "gamemode": true
  },
  "chat": {
    "formatEnabled": true,
    "format": "{prefix}{displayname}{suffix}: {message}",
    "defaultPrefix": "",
    "defaultSuffix": ""
  },
  "logging": {
    "level": "INFO",
    "logPermissionChecks": false,
    "logCommands": true,
    "logModifications": true
  },
  "performance": {
    "cacheEnabled": true,
    "cacheSize": 1000,
    "cacheTTL": 300
  }
}

Configuration Sections

Server Settings

json

"server": {
  "name": "My Hytale Server",
  "syncInterval": 300
}

name - Your server's display name (shown in web editor)
syncInterval - How often to sync permissions across the network (in seconds)

Storage Settings

json

"storage": {
  "type": "json",
  "autoSave": true,
  "autoSaveInterval": 300,
  "backups": {
    "enabled": true,
    "interval": 3600,
    "maxBackups": 24
  }
}

type - Storage backend type. Currently supported: json
autoSave - Automatically save changes to disk
autoSaveInterval - Auto-save interval in seconds
backups.enabled - Enable automatic backups
backups.interval - Time between backups in seconds
backups.maxBackups - Maximum number of backups to keep

Database storage (MySQL, PostgreSQL) is planned for a future release. JSON storage works well for most servers.

Web Editor Settings

json

"webEditor": {
  "enabled": true,
  "url": "https://hyperperms.dev/editor",
  "sessionTimeout": 86400
}

enabled - Enable or disable the web editor feature
url - URL of the web editor instance (use default or self-hosted)
sessionTimeout - How long editor sessions last in seconds (default: 24 hours)

If you're self-hosting the web editor, change the URL to your own instance. See the self-hosting guide for setup instructions.

Default Settings

json

"defaults": {
  "group": "default",
  "applyDefaultGroup": true
}

group - The default group for new players
applyDefaultGroup - Automatically assign new players to the default group

Context Settings

json

"contexts": {
  "world": true,
  "gamemode": true
}

world - Enable world-based context permissions
gamemode - Enable gamemode-based context permissions

Learn more about contexts in the contexts guide.

Chat Format Settings

json

"chat": {
  "formatEnabled": true,
  "format": "{prefix}{displayname}{suffix}: {message}",
  "defaultPrefix": "",
  "defaultSuffix": ""
}

formatEnabled - Enable HyperPerms chat formatting
format - Chat message format template
defaultPrefix - Default prefix for players without one
defaultSuffix - Default suffix for players without one

Available format placeholders:

{prefix} - Player's prefix from their highest-weight group
{suffix} - Player's suffix from their highest-weight group
{displayname} - Player's display name
{username} - Player's actual username
{group} - Player's primary group name
{message} - The chat message

Logging Settings

json

"logging": {
  "level": "INFO",
  "logPermissionChecks": false,
  "logCommands": true,
  "logModifications": true
}

level - Logging level: DEBUG, INFO, WARNING, ERROR
logPermissionChecks - Log every permission check (verbose, for debugging)
logCommands - Log HyperPerms commands executed
logModifications - Log changes to groups, users, and permissions

Enabling logPermissionChecks generates a lot of log output and may impact performance. Only enable for debugging purposes.

Performance Settings

json

"performance": {
  "cacheEnabled": true,
  "cacheSize": 1000,
  "cacheTTL": 300
}

cacheEnabled - Enable permission result caching
cacheSize - Maximum number of cached permission results
cacheTTL - Cache time-to-live in seconds

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

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",
    "autoSaveInterval": 600,
    "backups": {
      "enabled": true,
      "maxBackups": 10
    }
  },
  "performance": {
    "cacheEnabled": true,
    "cacheSize": 500
  }
}

Large Server (100+ Players)

json

{
  "storage": {
    "type": "json",
    "autoSaveInterval": 120,
    "backups": {
      "enabled": true,
      "interval": 1800,
      "maxBackups": 48
    }
  },
  "performance": {
    "cacheEnabled": true,
    "cacheSize": 5000,
    "cacheTTL": 600
  }
}

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