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