Skip to content

Global settings

Global settings are stored in config/greatnpc/settings.json. The JSON serializer uses the camelCase field names listed below. Snake_case names such as mysql_enabled are the editor's internal transport fields, not the JSON file schema.

The current settings data class has 15 properties. Unspecified properties keep their class defaults.

Defaults

{
  "autoMigrate": false,
  "autoMigrateEasyNpc": false,
  "autoReload": true,
  "clickCooldownMs": 1000,
  "useOwnEditor": true,
  "debugBattle": false,
  "theme": "dark",
  "menuCategoryPermissions": "",
  "mysqlEnabled": false,
  "mysqlHost": "localhost",
  "mysqlPort": 3306,
  "mysqlDatabase": "greatnpc",
  "mysqlUser": "root",
  "mysqlPassword": "",
  "mysqlPrefix": "greatnpc_"
}
JSON property Type Default Purpose
autoMigrate Boolean false Enable the supported legacy trainer-entity migration on entity load.
autoMigrateEasyNpc Boolean false Enable supported Easy NPC entity migration on load.
autoReload Boolean true Start the JSON configuration watcher.
clickCooldownMs Integer 1000 Minimum time between handled NPC clicks, in milliseconds.
useOwnEditor Boolean true Prefer the GreatNPC editor for supported NPC-editor interactions.
debugBattle Boolean false Enable the mod's diagnostic switch, including synchronized client diagnostics.
theme String "dark" GUI theme: dark or light.
menuCategoryPermissions String "" Optional category-to-permission mappings.
mysqlEnabled Boolean false Enable the optional MySQL/MariaDB battle-history backend.
mysqlHost String "localhost" Database server hostname.
mysqlPort Integer 3306 Database server port.
mysqlDatabase String "greatnpc" Existing database/schema name.
mysqlUser String "root" Database account name; this is the code default, not a required account.
mysqlPassword String "" Database password.
mysqlPrefix String "greatnpc_" Prefix for battle-history tables.

Migration settings enable conversions; they are not a compatibility guarantee for every source-mod version or custom model. Review the migration commands and use a world backup before enabling automatic conversion.

Category permissions

menuCategoryPermissions accepts semicolon-separated or newline-separated category=permission.node pairs. Category matching ignores case.

{
  "menuCategoryPermissions": "gyms=greatnpc.category.gyms;elite=greatnpc.category.elite"
}

This is a partial settings example. A category without a matching mapping has no additional category permission from this setting. These menu restrictions do not replace the NPC's own battle permissions and conditions.

Editing and validation

The server settings GUI writes these camelCase values to disk. Its input handling clamps click cooldown to 0–10000 ms and port to 1–65535, trims several text fields, and restricts the displayed theme to dark or light. Reading the JSON file directly does not run that same GUI validation; use valid types and values rather than relying on clamping of hand-edited files.

The effective click cooldown cannot be negative. The database table prefix is sanitized to ASCII letters, digits and underscores when used.

The GUI masks an existing password as ********. Leaving that mask unchanged preserves the stored password. The file itself contains the actual password, so keep it out of public screenshots, reports and source control.

Saving database changes through the GUI flushes queued history before switching settings and clears the history cache/connection. After manually editing the file, restart the server to ensure the global settings are read consistently. The configuration watcher primarily reloads trainer definitions; it does not turn settings.json into a universal live-reload API.

There is no global language setting here. Each client's language and resource packs control built-in translations; see Localization.