It's back! Gamma is now under active development, focusing mainly on an async reimplementation of the core proxy. You can see the latest developments on the development branch. You may also want to join the Discord Server!!
Gamma is a reverse proxy for Minecraft networks implemented in Python using asyncio. Gamma supports relaying traffic between multiple client connections to multiple servers. Players are proxied to the respective server depending on the hostname included in the first connection packet.
| Status | Feature | Description |
|---|---|---|
| ✅ | Asynchronous I/O | Gamma is written around asynchronous network communication, which brings a multitude of benefits such as lower memory usage. |
| ✅ | Multiple Players | Gamma supports multiple simultaneous player (client) connections. |
| ✅ | Multiple Backends | Gamma supports multiple configured backends (Minecraft servers). |
| ✅ | Packet Pipeline | Gamma allows users to easily implement PacketHandler subclasses and register them in the packet pipeline of any Connection object. |
| ✅ | Packet Pipeline | Gamma allows users to easily implement PacketHandler subclasses and register them in the packet pipeline of any Connection object. |
| ✅ | Config Manager | Backend configuration management has not been implemented in the async rewrite just yet. |
| 🚧 | Proxy Protocol | Support for sending client addresses to upstream server using the PROXY TCP4 header has not been implemented in the async rewrite just yet. |
| ❌ | Terminal Interface | Terminal interface using the Textual package that displays per-player or global connection information. |
| ❌ | Docker Support | Docker containerization config (dockerfile) |
| ❌ | Crosstalk | Peer discovery and communication mechanism allowing your distributed Gamma instances discover and communicate player + network information with each-other. |
| Step | Description | Command |
|---|---|---|
| 1 | Clone repo | git clone https://github.com/mitch0s/gamma/ |
| 2 | Change directory to 'gamma/' | cd gamma/ |
| 3 | Create Python Virtual Environment (venv) | python -m venv venv |
| 4 | Activate Virtual Environment | ./venv/Scripts/activate (Note: activation command different on MacOS/Linux) |
| 5 | Install Package Requirements | pip install -r requirements.txt |
| 6 | Change directory to 'src/' | cd src/ |
| 7 | Start Gamma | python main.py |
| 8 | Done | Gamma should now running in the same terminal. |
- Minecraft client (client) sends DNS request to resolve some hostname.
- DNS server resolves and returns an IPv4 address to the client. This address points to a machine running Gamma.
- Client connects to the machine running Gamma, and sends a handshake packet that includes the user-entered hostname ('server.com').
- While no upstream connection is established, Gamma buffers packets from the client and scans them for the hostname (and later username).
- Once the hostname is extracted, Gamma requests a config for the specified hostname.
- If no config for the hostname is found, Gamma responds with an "invalid hostname" MOTD/Disconnect message, and closes the connection.
- ConnectionRelay reads the hostname config and opens a connection to the specified host:port (+some other logic depending on config).
- The buffered handshake packets received from client earlier are forwarded to upstream server.
- ConnectionRelay enters 'forwarding' mode, and directly passes packets between upstream and downstream until one of the connections are closed.
- Packets are passed through PacketHandler instances registered with the Connection instance being read from before being forwarded.
Gamma is partly inspired by infrared.