Document complete Velocity forwarding requirements per game type including gotchas
This commit is contained in:
parent
e9d0d67d36
commit
3f117ade7e
117
SCRATCH/minecraft-velocity-forwarding.md
Normal file
117
SCRATCH/minecraft-velocity-forwarding.md
Normal file
@ -0,0 +1,117 @@
|
||||
# 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)
|
||||
Loading…
Reference in New Issue
Block a user