118 lines
4.9 KiB
Markdown
118 lines
4.9 KiB
Markdown
# 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:
|
||
```toml
|
||
[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`:
|
||
```yaml
|
||
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
|
||
```properties
|
||
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-<version>.jar | vanilla, fabric |
|
||
| ProxyCompatibleForge | /opt/zlh/addons/proxy-compatible-forge/pcf-<version>.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)
|