Terraria Compatibility Launcher (TCL)

Terraria Compatibility Launcher (TCL) is a local compatibility tunnel for Terraria clients.

With the arrival of Terraria 1.4.5.x, many times the local client version does not match the server version. This launcher solves that by detecting the server version and patching your local version string during the initial handshake.

The main goal is simple: run the launcher, connect your game to localhost, and join servers with fewer version mismatch issues.

Primary Usage (Recommended)

Use the packaged executable:

• dist/TCL.exe

No Python setup is required for this mode.

Quick Start (Using the EXE)

1. Run dist/TCL.exe.
2. In Destination, enter HOST:PORT (example: ceniza.sytes.net:7777).
3. Click Launch Tunnel.
4. In Terraria, connect to:
   • IP: 127.0.0.1
   • Port: the local port shown in the launcher (default 7777)
5. Keep the launcher open while you play.

What the Launcher Does

1. Opens a local tunnel on 127.0.0.1 (default port 7777).
2. Connects to the remote Terraria server you entered.
3. Probes server compatibility version when needed.
4. Rewrites the first handshake version packet from the local client.
5. Forwards traffic normally after synchronization.

Technical Flow

This is the internal behavior at protocol level:

1. TCL starts a local TCP listener (127.0.0.1:7777 by default) using asynchronous sockets.
2. When the game connects, TCL opens a second TCP connection to the real remote server.
3. The first Terraria connect packet is inspected.
   • Packet type: 1 (Connect Request)
   • Payload: Terraria version string (for example Terraria319)
4. If needed, TCL rewrites only the version string in that first packet and rebuilds packet length and payload.
5. After that, tunnel mode becomes transparent:
   • client -> TCL -> server
   • server -> TCL -> client
6. Version discovery mode sends controlled probes across known version ranges and validates server responses before selecting a target version.

This design keeps intervention minimal: only the initial handshake version field is patched, while the rest of traffic is forwarded as-is.

Main Features

• Automatic server version discovery.
• Optional forced version (Advanced Settings).
• Optional custom local listening port.
• Real-time tunnel logs.
• Quick copy buttons for local IP and port.

Screenshots

Show Screenshots

1) Launcher Opened

2) Destination Configured

3) Tunnel Active

4) Advanced Settings

5) In-Game Connection Details

Optional Developer Usage

If you need to deploy or run from Python source instead of the EXE:

Requirements:

• Python 3.10+
• PyQt5

Install dependency:

• pip install pyqt5

Run options:

• GUI: python TCL_GUI.py
• CLI: python TCL_CLI.py HOST:PORT [--version ] [--debug]

Notes

• Focused on handshake compatibility tunneling.
• Support depends on the implemented version detection and filtering logic.
• Test in a controlled environment before wide deployment.

Credits

Created and maintained by:

• @isawicca
• magaflaca@proton.me

License

MIT License. See LICENSE.