Configuration

Location

<plugin data dir>/config.json. NetworkCore writes a default file on first boot if none exists, with the values shown below.

Full config

{
    "server": {
        "id": null,
        "role": "lobby"
    },
    "redis": {
        "host": "127.0.0.1",
        "port": 6379,
        "password": null,
        "database": 0,
        "key_prefix": "network:",
        "tls": false,
        "verify_peer": true
    },
    "network": {
        "auth_token": null
    },
    "metrics": {
        "enabled": true,
        "bind": "127.0.0.1",
        "port": 9100,
        "path": "/metrics"
    },
    "rpc": {
        "timeout_ms": 5000
    },
    "mysql": {
        "enabled": false,
        "host": "127.0.0.1",
        "port": 3306,
        "database": "kweebec",
        "user": "kweebec",
        "password": null,
        "max_pool_size": 10,
        "min_idle": 2,
        "connection_timeout_ms": 5000,
        "idle_timeout_ms": 600000,
        "max_lifetime_ms": 1800000,
        "use_ssl": false
    }
}

Fields

server

Field	Default	Meaning
`id`	`null`	Optional fixed server id. If null, auto-generated as `<role>-<8 hex chars>` (e.g. `lobby-3f2a91bd`) on every boot. Set this when you want a stable id across restarts.
`role`	`"lobby"`	Logical role of this server. Used to filter via `ServerRegistry.getServersByRole(...)`. Examples: `lobby`, `bridge_duel`, `arena`. Use snake_case.

redis

Field	Default	Meaning
`host`	`"127.0.0.1"`	Redis host
`port`	`6379`	Redis port
`password`	`null`	Redis AUTH password. Prefer the env var (below).
`database`	`0`	Redis logical database (0-15 on stock Redis)
`key_prefix`	`"network:"`	All keys NetworkCore writes start with this prefix. Server registry keys end up at `network:servers:<id>`. Change this only if you're sharing a Redis with something unrelated.
`tls`	`false`	Enables TLS for the Redis connection (Lettuce `rediss://` equivalent). Set to true whenever Redis is on a different host than the Hytale server, since the connection crosses untrusted network.
`verify_peer`	`true`	When `tls` is on, verifies the Redis server's certificate against the JVM's default trust store. Set to false only in dev / against self-signed certs. Logs a warning when disabled.

network

Field	Default	Meaning
`auth_token`	`null`	Shared secret. When set, every outgoing envelope is stamped with this token and every inbound message is rejected unless its token matches. When null, no auth is enforced. Use the env var.

metrics

Field	Default	Meaning
`enabled`	`true`	Turn the whole metrics system on/off. When off, `getMetrics()` returns null.
`bind`	`"127.0.0.1"`	Address to bind the Prometheus HTTP server. Defaults to loopback so it's not exposed to the public internet. Set to `0.0.0.0` only if you've put auth / a reverse proxy in front.
`port`	`9100`	Port for the Prometheus exporter
`path`	`"/metrics"`	URL path. Standard convention is `/metrics`.

rpc

Field	Default	Meaning
`timeout_ms`	`5000`	How long an RPC request waits for a response before completing the future exceptionally with `TimeoutException`.

mysql

Field	Default	Meaning
`enabled`	`false`	Master switch. When false, `getDatabase()` returns null and no pool is created. Set to true once you've put real credentials in place.
`host`	`"127.0.0.1"`	MySQL host.
`port`	`3306`	MySQL port.
`database`	`"kweebec"`	Database (schema) name. Must exist before NetworkCore boots; we don't auto-create databases.
`user`	`"kweebec"`	MySQL user.
`password`	`null`	MySQL password. Prefer the env var.
`max_pool_size`	`10`	Hikari `maximumPoolSize`.
`min_idle`	`2`	Hikari `minimumIdle`.
`connection_timeout_ms`	`5000`	Hikari `connectionTimeout`.
`idle_timeout_ms`	`600000` (10 min)	Hikari `idleTimeout`.
`max_lifetime_ms`	`1800000` (30 min)	Hikari `maxLifetime`. Keep below MySQL's `wait_timeout`.
`use_ssl`	`false`	Adds `useSSL=true` to the JDBC URL. Turn on whenever MySQL is on a different host than the Hytale server.

Environment variable overrides

These take precedence over the config file at boot time. Use them for secrets so the config file stays safe to check into version control.

Env var	Overrides
`REDIS_PASSWORD`	`redis.password`
`NETWORK_AUTH_TOKEN`	`network.auth_token`
`MYSQL_PASSWORD`	`mysql.password`

Recommended setup per environment

Local dev (single server):

Defaults are fine. Run Redis on localhost, don't set the auth token.

Multi-server staging or production:

server.id left null is fine if you're OK with the id changing on every boot. Set it to something stable like lobby-prod-01 if you want logs and dashboards to keep continuity across restarts.
server.role set explicitly per server. This is what dashboards and routing use.
redis.host pointed at your shared Redis. redis.password not in the file; set REDIS_PASSWORD env var.
redis.tls on whenever Redis is on a different host than the Hytale server. verify_peer stays true unless Redis uses a self-signed cert you haven't loaded into the JVM trust store.
network.auth_token not in the file; set NETWORK_AUTH_TOKEN env var to the same value on every server.
metrics.bind stays 127.0.0.1. Run Prometheus on the same host (or use an SSH tunnel / reverse proxy with auth to expose it elsewhere).

5.6 KiB Raw Blame History