core-vitals/docs/03_Configuration.md

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:"
    },
    "network": {
        "auth_token": null
    },
    "metrics": {
        "enabled": true,
        "bind": "127.0.0.1",
        "port": 9100,
        "path": "/metrics"
    },
    "rpc": {
        "timeout_ms": 5000
    }
}

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.

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.

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

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.
• 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).