Network

network.yml configures multi-server / multi-proxy network mode - cross-server /rtp where a player on one backend is teleported into a region served by another. It is disabled by default.

When network.enabled: false, this file is read, validated, and otherwise ignored: no threads start, no database tables are created, no transport opens. The backend behaves byte-identically to a build without network mode.

This is distinct from the simpler network.redis block in config.yml, which only shares cached locations within a single network and does not enable cross-server routing.

network (backend identity)

Key	Default	Purpose
enabled	false	Opt this backend into the cross-server network.
serverId	""	Stable backend identity. Required when enabled: true. Two backends sharing a serverId overwrite each other's heartbeat row.
secretEnv	RTP_NET_SECRET	Environment variable holding the shared HMAC secret. Required when enabled: true and transport.type: redis; optional for the SQL binding (DB auth + TLS is the security boundary there).

transport (backing store for cross-process state)

transport.type selects how backends share state:

Value	Behaviour
auto	Recommended start. No database. Detects a BungeeCord/Velocity proxy and gossips region availability over its plugin-messaging channel; falls back to local-only when no proxy is found.
plugin-message	Forces the proxy plugin-messaging transport without auto-detection. No database. Availability is best-effort (only as fresh as the last heartbeat seen over a player connection). Not for very large multi-proxy networks.
in-memory	Development only; nothing leaves the JVM.
sql	DB-as-bus. Reuses the existing RTP database pool. Durable across restarts.
redis	Jedis-backed heartbeats + pub/sub. Heartbeats and snapshots work; atomic claim (for cross-backend reservation tokens) is not yet available.

• transport.pluginMessage.channel (default bungeecord:main) - proxy channel for the auto/plugin-message tiers.
• transport.redis.host / port / password (default localhost / 6379 / empty) - used only when type: redis.

heartbeat (state publication cadence)

Key	Default	Purpose
intervalMs	1000	How often this backend publishes its state row (and, on the plugin-message tier, the gossip cadence).
staleAfterMs	5000	How long a peer's last-seen state stays trusted before it is treated as unknown. Keep comfortably above intervalMs.

routing (backend-side router)

Key	Default	Purpose
mode	local	local = never enrol into the cross-server wait queue (zero behaviour change). auto = prefer local, enrol only when local cannot serve the region. always = always enrol (developer/acceptance only).
lobbyMode	false	When true, this backend becomes a pure dispatch node: it advertises no regions, and a bare /rtp auto-routes to the peer+region with the most kept locations ("most-kept" policy).

queue (cross-server wait queue)

Ignored when network.enabled: false or routing.mode: local.

Key	Default	Purpose
maxDepth	50	Max buffered enrolments before backpressure rejects new /rtp calls (QUEUE_FULL).
flushIntervalMs	250	Backend dirty-write flush cadence (ms).
pollIntervalMs	1000	Backend status-cache poll cadence (ms); drives per-player progress refresh.
entryTtlMs	0	Optional passive aging of envelope hashes. 0 disables.
crossServerRequestsPerSecond	5	Cross-server enrolment rate limit (token-bucket refill).
crossServerRequestsBurst	10	Token-bucket burst capacity.
workerThreads	1	Proxy-side BLPOP worker count. Increase only when a single worker saturates.

reservation (reservation-token lifecycle)

Key	Default	Purpose
reapIntervalMs	30000	Proxy-side TTL reaper cadence (ms). Sweeps expired tokens and releases their coordinate.
ttlMs	60000	Per-token TTL (ms). A claimed-but-unconsumed reservation older than this is treated as abandoned.

regionCollision

policy (default warn) - what to do when two backends advertise the same region name. Only warn is shipped; unknown values degrade to warn.

servers (optional per-destination overlay)

Never required - backends announce themselves over the proxy, so the destination list assembles itself. Add an entry (matched by serverId) only to override policy for one destination. Each entry supports permission, display-name, hide-when-unavailable, and allow-when-unavailable. Commented out by default.

loadBalancer (blank-/rtp region selection scoring)

Lower score wins. Each terms entry scores a backend by one metric through a curve; scores sum, divide by backend weight, and ties break by serverId then region. The shipped defaults mirror "most-kept wins" with smooth fall-off, gating overloaded backends via step curves on heap and region.

• Inputs: mspt, queueDepth, heapUsed, heapFree, playerCount, keptCount, tps, keptRegion.
• Curves: linear, exponential (k), logarithmic (k), sigmoid (k, x0), step (threshold), power (p). Ranges: k 0.1-20, p 0.1-8, x0/threshold 0-1.

Default term	input	weight	curve
mspt	mspt	1.0	sigmoid k=8.0, x0=0.6
queue	queueDepth	1.0	exponential k=3.0
heap	heapUsed	5.0	step threshold=0.85
region	keptRegion	5.0	step threshold=0.95
kept	keptCount	0.25	logarithmic k=9.0

regionScarcityWeight defaults to 0 because the explicit region term above already owns the kept-region signal.

For setup walkthroughs and verification, see the proxy admin docs (single-backend, cross-server).