jester/zlh-grind
1
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases Wiki Activity
main
zlh-grind/SCRATCH/minecraft-velocity-forwarding.md

4.9 KiB
Raw Permalink Blame History

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

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