Minecraft Velocity Forwarding — Per Game Type Requirements

Overview

Velocity must be set to player-info-forwarding-mode = "modern" for production. Each game type requires a specific mod/config injected at provisioning time. The forwarding secret from forwarding.secret must be injected into each container.

Per Game Type

Vanilla

❌ Pure vanilla JAR does NOT support modern forwarding
✅ Solution: Replace vanilla JAR with Fabric loader + FabricProxy-Lite mod
Player experience: identical to vanilla — no gameplay changes
Agent provisioning: pull Fabric loader as server.jar from artifact server, drop FabricProxy-Lite into mods/, write forwarding secret to config/FabricProxy-Lite.toml

Fabric

✅ Supported via FabricProxy-Lite mod
Agent provisioning: drop FabricProxy-Lite into mods/, write forwarding secret to config/FabricProxy-Lite.toml
Config file format:

[general]
secret = "your-forwarding-secret-here"
hackOnlineMode = false
hackEarlyPlayerInit = true

Also supports env vars: FABRIC_PROXY_SECRET, FABRIC_PROXY_HACK_ONLINE_MODE

Paper

✅ Native support — no extra mod needed
Paper 1.14+ supports modern forwarding natively
Agent provisioning: write to config/paper-global.yml:

proxies:
  velocity:
    enabled: true
    online-mode: false
    secret: "your-forwarding-secret-here"

For Paper 1.18.2 or lower: settings are in paper.yml under settings.velocity-support.*

Forge (1.20.2+)

✅ Supported via ProxyCompatibleForge (PCF) mod
Download: https://modrinth.com/mod/proxy-compatible-forge
Agent provisioning: drop PCF jar into mods/, write secret to config/pcf-common.toml
⚠️ Known issue: If server has many mods, players may disconnect with QuietDecoderException: too many known packs
- Fix: add -Dvelocity.max-known-packs=128 (or higher) to Velocity startup args
- This is a Velocity-side fix not a per-container fix
Forge 1.13–1.20.1: Use Ambassador plugin on Velocity instead

NeoForge

✅ Supported via ProxyCompatibleForge (PCF) mod (same as Forge)
Alternative options: NeoVelocity, NeoForwarding, NeoForged Velocity Support (all on Modrinth)
PCF is recommended as it's the most actively maintained
Agent provisioning: same as Forge above
⚠️ Same max-known-packs issue applies for large modpacks
⚠️ If using Sinytra/Connector (Fabric mods on NeoForge): compatibility issues exist with PCF — use NeoVelocity instead and set login-custom-packet-catchall = false in config

Velocity-Side Requirements

server.properties for all containers

online-mode=false

This must be set on every backend container regardless of game type.

forwarding.secret

Lives at /opt/velocity/forwarding.secret
Must be injected into each container config at provisioning time
Agent needs to read this secret from a known path or env var

max-known-packs (Forge/NeoForge with many mods)

Default Velocity limit: 64 known packs
Modpacks can easily exceed this
Add to Velocity startup: -Dvelocity.max-known-packs=256
This is a global Velocity setting — set it high by default

Agent Provisioning Requirements per Game Type

Game Type	server.jar source	Extra mod needed	Config to write
vanilla	Fabric loader JAR	FabricProxy-Lite	config/FabricProxy-Lite.toml
fabric	Fabric loader JAR	FabricProxy-Lite	config/FabricProxy-Lite.toml
paper	Paper JAR	None	config/paper-global.yml
forge	Forge installer	ProxyCompatibleForge	config/pcf-common.toml
neoforge	NeoForge installer	ProxyCompatibleForge	config/pcf-common.toml

Artifact Server Requirements

Mods to host on zlh-artifacts:

Mod	Path	Used by
FabricProxy-Lite	/opt/zlh/addons/fabricproxy-lite/fabricproxy-lite-.jar	vanilla, fabric
ProxyCompatibleForge	/opt/zlh/addons/proxy-compatible-forge/pcf-.jar	forge, neoforge

Keep latest version of each — update when new Minecraft versions are released.

Known Gotchas

Vanilla JAR cannot be used — must swap to Fabric loader for vanilla game type
online-mode=false required on every backend server
Forwarding secret must match exactly — no extra spaces or newlines
Large modpacks hit max-known-packs limit — set -Dvelocity.max-known-packs=256 on Velocity globally
Sinytra/Connector + PCF incompatibility — if customer runs Fabric mods on NeoForge via Connector, use NeoVelocity not PCF
Forge 1.13-1.20.1 — PCF does not support these versions, need Ambassador plugin on Velocity
Paper 1.12.2 and below — modern forwarding not supported, need legacy BungeeCord forwarding (not relevant for current Minecraft versions)
After Velocity restart — all containers must be re-registered via API resync endpoint (not yet implemented)

4.9 KiB Raw Blame History Unescape Escape