WSMC
Adds WebSocket support for Minecraft Java Edition. Most CDN providers (especially in free tiers) do not support raw TCP proxy traffic. Thanks to this mod, server owners can hide their server behind a CDN and allow players to connect via WebSocket, providing protection against DDoS attacks.
Compatibility: Minecraft 1.20.2, Forge and Fabric. The mod works standalone and does not require additional dependencies.
Server Functionality
- Server allows players to connect via WebSocket
- Standard TCP connection capability is preserved
- TCP and WebSocket connections are handled through a single port
- Players without this mod on the client can connect to the server via regular TCP
- Server can obtain client statistics (e.g., real IP address) from WebSocket handshake
Client Functionality
- Client can connect to WebSocket-enabled servers using URI like
ws://hostname.com:port/path_to_minecraft_endpoint - Ability to connect to any servers via standard TCP using regular syntax
hostname_or_ip:portis preserved
Important Features
- Mod does not affect gameplay
- Does not modify user interface
- Regular clients can connect to your server even with the mod installed (other mods may restrict this capability)
- Installing the mod on the client does not interfere with connecting to regular or modded servers
- Server can obtain real IP addresses of players connected via CDN-proxied WebSocket
- Compatible with other TCP-WebSocket proxies such as websocat
Configuration
Mod configuration is passed through JVM system properties using the -D parameter in the command line.
| Property Key | Type | Purpose | Side | Default | Example |
|---|---|---|---|---|---|
| wsmc.disableVanillaTCP | boolean | Disable standard TCP login and server status | Server | false | true |
| wsmc.wsmcEndpoint | string | Set WebSocket Endpoint for Minecraft login and server status. If property is not set, client can connect via ANY WebSocket Endpoint. Must start with /, case-sensitive | Server | Not set | /mc |
| wsmc.debug | boolean | Show debug logs | Server/Client | false | true |
| wsmc.dumpBytes | boolean | Save raw WebSocket binary frames. Works only if wsmc.debug is set to true |
Server/Client | false | true |
For Developers
On the server side, if a client connects via WebSocket, its handshake request is accessible through the standard net.minecraft.network.Connection class. To obtain this information, cast a Connection instance to IConnectionEx, then call IConnectionEx.getWsHandshakeRequest().
This is useful for obtaining information about the original request if the Minecraft server is behind a reverse proxy (e.g., CDN). For example, headers X-Forwarded-For and CF-IPCountry indicate the client's IP address and country code respectively.
