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": {
        "url": null,
        "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
`url`	`null`	Full Redis connection URI. Supports both `redis://` (plain) and `rediss://` (TLS). When set, all other redis fields are ignored (host, port, password, database, tls). This is what you want when your provider hands you a one-line connection string. Prefer the env var (below) over putting credentials in the file.
`host`	`"127.0.0.1"`	Redis host. Only used when `url` is null.
`port`	`6379`	Redis port. Only used when `url` is null.
`password`	`null`	Redis AUTH password. Only used when `url` is null. Prefer the env var.
`database`	`0`	Redis logical database (0-15 on stock Redis). Only used when `url` is null.
`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. Applies regardless of `url`.
`tls`	`false`	Enables TLS for the Redis connection. Only used when `url` is null (the URI scheme picks TLS on/off when `url` is set). 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 (via `tls: true` or a `rediss://` url), 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_URL`	`redis.url` (full connection URI)
`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.
Easiest path for hosted Redis: set REDIS_URL env var to the rediss://user:pass@host:port/0 string your provider gives you. Leave the host/port/password/database fields at defaults. The rediss:// scheme already implies TLS - no need to touch tls.
Alternative: set redis.host / redis.port explicitly, put the password in REDIS_PASSWORD, and set redis.tls: true. Works the same; just more fields to keep in sync across servers.
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).

6.3 KiB Raw Blame History