Proxy Compatible Forge

Proxy Compatible Forge

Special thanks to FabricProxy-Lite and
CrossStitch for spearheading in the modded proxy space. We've done
our fair share of work porting things and tailoring them to a Neo/Forge environment, but nonetheless we stand on the shoulders of giants.

This mod brings Velocity's modern,
Lucko's BungeeGuard, and
BungeeCord's legacy player info forwarding modes to Neo/Forge servers.

Supported Versions/Platforms

• Forge versions 1.7.2 - 26.2
  • MixinBootstrap is required on Forge 1.14 - 1.15.1
  • ModernMixins is required on Forge 1.13.x
  • MixinBooter is required on Forge 1.8 - 1.12.2
  • UniMixins is required on Forge 1.7.x
  • 1.7.2 - 1.12.2 also require a modified Velocity proxy
• NeoForge versions 1.20.1 - 26.2
• SpongeForge/SpongeNeo
  • PCF shouldn't be needed, as Sponge supports legacy+modern forwarding and command argument wrapping
  • However, if Forgified Fabric API is installed (specifically fabric_networking_api_v1), you may need to use PCF and disable Sponge's forwarding
• Bukkit+Neo/Forge Hybrid servers
  • Use the Hybrid's built-in forwarding support when possible, otherwise use PCF if their implementation is incompatible

See the Compatibility page for more details on supported platforms and modpacks.

How to Get Started

Note Regarding Forge 1.13 - 1.20.1

If you wish to host modern Forge server (1.13 - 1.20.1) behind a Velocity proxy, check out Ambassador: https://modrinth.com/plugin/ambassador

Note: Version 1.2.0-beta or higher of Ambassador doesn't require this mod anymore, but you can still use it if you want modern forwarding.

Installation

The following assumes you've already configured a Velocity proxy and have a functional setup.

1. Download this mod and place it in your Neo/Forge server's mods folder (Jars can be found on Modrinth or in the releases tab).
2. Start the Neo/Forge server to generate the default config file.
3. Stop the Neo/Forge server.
4. Open proxy-compatible-forge.toml in the config folder and put your forwarding secret in the forwarding.secret config field.
5. In server.properties make sure online-mode is set to false.
6. You are now ready to start the server and connect to it with Velocity!

Configuration

The config is located under config/proxy-compatible-forge.toml and has the following options:

Setting Group	Setting Name	Default Value	Description
forwarding	enabled	true	Enable or disable player info forwarding. Changing this setting requires a server restart.
forwarding	mode	"MODERN"	The type of forwarding to use.
forwarding	secret	""	The secret used to verify the player's connection is coming from a trusted proxy.
forwarding	approvedProxyHosts	[]	A list of approved proxy hostnames or IP addresses. If the connecting proxy's hostname or IP isn't in this list, the player will be disconnected. Leave empty to allow all.
crossStitch	enabled	true	Enable or disable CrossStitch support. Changing this setting requires a server restart.
crossStitch	forceWrappedArguments	[]	Add any incompatible modded or vanilla command argument types here.
crossStitch	forceWrapVanillaArguments	false	Force wrap vanilla command argument types. Useful for when the above setting gets a bit excessive.
debug	enabled	false	Enable or disable debug logging.
debug	disabledMixins	[]	List of mixins to disable. Use the Mixin's name and prefix it with it's partial or full package name.
advanced	modernForwardingVersion	"NO_OVERRIDE"	Overrides the modern forwarding version decided by PCF. Change it to "MODERN_DEFAULT" if you encounter chat-signing issues. Changing this setting requires a server restart.

Features

Player Info Forwarding

As mentioned above, PCF implements Velocity's MODERN forwarding protocol, allowing you to secure modded
servers behind proxies.

Modern Forwarding versions 1-4 are supported:

Name	Value	Supported MC Versions
MODERN_DEFAULT	1	Any
MODERN_FORWARDING_WITH_KEY	2	1.19
MODERN_FORWARDING_WITH_KEY_V2	3	1.19.1 - 1.19.2
MODERN_LAZY_SESSION	4	1.19.3 and above

If you run into compatibility issues regarding chat signing, report the issue, then change
advanced.modernForwardingVersion to MODERN_DEFAULT in PCF's config.

Next, BUNGEEGUARD forwarding requires you to either use Velocity's BUNGEEGUARD forwarding mode, or use BungeeCord
with the BungeeGuard plugin installed.

Lastly, LEGACY forwarding requires you to use Velocity's LEGACY forwarding mode or BungeeCord with IP forwarding enabled.
It is advised that you do not use this forwarding mode, but you can use the forwarding.approvedProxyHosts setting to somewhat secure things.

Modded Command Argument Wrapping, aka CrossStitch

This resolves errors such as:

io.netty.handler.codec.CorruptedFrameException: Error decoding class com.velocitypowered.proxy.protocol.packet.AvailableCommandsPacket

PCF ports this Fabric mod's ability to wrap modded command arguments, allowing them to be sent through Velocity without
there needing to be a custom packet deserializer for each and every command argument mods add. Please note that BungeeCord
does not support wrapped command arguments, so you will likely need to disable this feature if you use (or run a fork of) BungeeCord.

In some rare cases mods will register their command arguments under the minecraft namespace or make modifications to
vanilla arguments, bypassing PCF's argument wrapper. In such cases, you can add the custom argument's ID to PCF's
crossStitch.forceWrappedArguments setting to force PCF to wrap the argument.

In situations where mods inject and register their arguments before Vanilla does, offsetting all the argument ID values,
you can enable the crossStitch.forceWrapVanillaArguments setting to force-wrap the minecraft and brigadier namespaces.
This is more of a band-aid solution as the offset argument IDs cannot be read by Velocity, and if the argument IDs on
the client have the same offset Velocity commands cannot be read by the client, preventing connections entirely unless
you disable all commands on the proxy via permissions or by removing plugins that add commands.

The easiest way to tell if this is happening is to enable PCF's debug logging in the config and check to see if
brigadier:boolean has an argument ID other than 0.

A common fix for this is for the mod in question to move their registration mixin to RETURN, and to ensure that their
argument's registration specifies their modid as the namespace.

If you find any wild args, please open an issue so we can add them to the default config, or so we can use the
information provided to write up a PR for the mod causing the issue.

Common Issues

Too Many Channels

Client Error:

Invalid payload REGISTER!

Velocity:

Velocity Fix: Add -Dvelocity.max-known-packs=# to the Velocity's startup arguments,
where # is a number that is 64 + number-of-mods*1.5 (round up).

Eg: For 40 mods, use 64 + 40*1.5 = 124, so -Dvelocity.max-known-packs=124

Paper Server Error:

[00:00:00 ERROR]: Couldn't register custom payload
java.lang.IllegalStateException: Cannot register channel 'modid:channel'. Too many channels registered!

Paper Fix: Add -Dpaper.disableChannelLimit=true to the Paper server's startup arguments

Notes: Due to the amount of channels and mods at play, textures/items may be mismatched on the client when joining a Vanilla server.

An internal server connection error occurred

Client Error:

An internal server connection error occurred.

Velocity Error:

io.netty.handler.codec.CorruptedFrameException: Packet sent for class com.velocitypowered.proxy.protocol.packet.PluginMessagePacket was too big (expected 1234567 bytes, got 7654321 bytes)

Resolved Velocity-side with the by adding -Dvelocity.max-plugin-message-payload-size=####### to Velocity's startup arguments,
where ####### is a bit larger than the last "got ####### bytes" number in the error message. Repeat until your client is able to log in.

Building the Project

1. Clone the repository. git clone https://github.com/adde0109/Proxy-Compatible-Forge.git

2. Run ./gradlew build (gradlew.exe build on Windows) in the root directory of the project

3. The jar will be in build/libs/