Document complete Velocity forwarding requirements per game type including gotchas

SCRATCH/minecraft-velocity-forwarding.md

@@ -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)