Main Configuration

Complete reference for the HyperPerms configuration file. All settings and their effects are documented here.

Configuration File Location

text
plugins/HyperPerms/config.json

Full Configuration Reference

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

Server Settings

json
"server": {
  "name": "My Hytale Server",
  "syncInterval": 300
}
OptionTypeDefaultDescription
namestring"Hytale Server"Server name shown in web editor
syncIntervalinteger300Seconds between network syncs (multi-server)

Storage Settings

json
"storage": {
  "type": "json",
  "autoSave": true,
  "autoSaveInterval": 300,
  "backups": {
    "enabled": true,
    "interval": 3600,
    "maxBackups": 24
  }
}
OptionTypeDefaultDescription
typestring"json"Storage backend type
autoSavebooleantrueAutomatically save changes to disk
autoSaveIntervalinteger300Seconds between auto-saves
backups.enabledbooleantrueEnable automatic backups
backups.intervalinteger3600Seconds between backups
backups.maxBackupsinteger24Maximum number of backups to keep

See the storage guide for more details.

Web Editor Settings

json
"webEditor": {
  "enabled": true,
  "url": "https://hyperperms.dev/editor",
  "sessionTimeout": 86400
}
OptionTypeDefaultDescription
enabledbooleantrueEnable the web editor feature
urlstring"https://hyperperms.dev/editor"Web editor URL (change for self-hosting)
sessionTimeoutinteger86400Session duration in seconds (24 hours)
If you're self-hosting the web editor, change the URL to your own instance. See the self-hosting guide.

Default Settings

json
"defaults": {
  "group": "default",
  "applyDefaultGroup": true
}
OptionTypeDefaultDescription
groupstring"default"Default group for new players
applyDefaultGroupbooleantrueAuto-assign new players to default group

Context Settings

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

Enable or disable context calculators. See the contexts guide.

Chat Format Settings

json
"chat": {
  "formatEnabled": true,
  "format": "{prefix}{displayname}{suffix}: {message}",
  "defaultPrefix": "",
  "defaultSuffix": ""
}
OptionTypeDefaultDescription
formatEnabledbooleantrueEnable HyperPerms chat formatting
formatstring(see above)Chat message format template
defaultPrefixstring""Default prefix if player has none
defaultSuffixstring""Default suffix if player has none

Format Placeholders

  • {prefix} - Player's prefix
  • {suffix} - Player's suffix
  • {displayname} - Player's display name
  • {username} - Player's username
  • {group} - Player's primary group
  • {message} - The chat message

Logging Settings

json
"logging": {
  "level": "INFO",
  "logPermissionChecks": false,
  "logCommands": true,
  "logModifications": true
}
OptionTypeDefaultDescription
levelstring"INFO"Log level: DEBUG, INFO, WARNING, ERROR
logPermissionChecksbooleanfalseLog every permission check (verbose)
logCommandsbooleantrueLog HyperPerms commands
logModificationsbooleantrueLog permission changes
Enabling logPermissionChecks creates significant log output and may impact performance. Use only for debugging.

Performance Settings

json
"performance": {
  "cacheEnabled": true,
  "cacheSize": 1000,
  "cacheTTL": 300
}
OptionTypeDefaultDescription
cacheEnabledbooleantrueEnable permission caching
cacheSizeinteger1000Max cached permission results
cacheTTLinteger300Cache time-to-live in seconds
Keep caching enabled for optimal performance. The cache is automatically invalidated when permissions change.

Reloading Configuration

After editing the configuration file:

text
/hp reload
Some settings require a full server restart, including:
  • Storage type changes
  • Some performance settings

See Also