Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ZTzTopia/GTProxy/llms.txt

Use this file to discover all available pages before exploring further.

GTProxy includes a built-in HTTPS web server that intercepts and modifies Growtopia’s server data requests. This allows the proxy to redirect the game client to connect through the local proxy server.

​
Overview

The web server intercepts the Growtopia client’s initial HTTPS request to retrieve server connection information. It forwards the request to the official server, modifies the response to point to the local proxy, and returns it to the client.

​
Server Configuration

​
port
integer
default:443
The HTTPS port where the web server listens.This is hardcoded to port 443 (standard HTTPS port) in the implementation (src/core/web_server.cpp:28). The server binds to 0.0.0.0 to accept connections from any network interface.
​
ssl_certificate
string
default:"./resources/cert.pem"
Path to the SSL certificate file.Required for HTTPS connections. The certificate must be trusted by the Growtopia client for secure connections.
​
ssl_private_key
string
default:"./resources/key.pem"
Path to the SSL private key file.Required for HTTPS connections. This key must correspond to the SSL certificate.

​
How It Works

The web server operates as follows:
  1. Client Request: The Growtopia client makes an HTTPS POST request to /growtopia/server_data.php
  2. Request Forwarding: The proxy forwards this request to the official server using the configured DNS resolver
  3. Response Modification: The proxy modifies the response to replace:
    • server field → 127.0.0.1 (localhost)
    • port field → The proxy server port from config (default: 16999)
    • type2 field → 1 (forces specific connection type)
  4. Client Connection: The client receives the modified response and connects to the local proxy
  5. Proxy Connection: The proxy then connects to the real server on behalf of the client

​
Request Interception

The web server intercepts the /growtopia/server_data.php endpoint (src/core/web_server.cpp:75): 
https_server_.Post("/growtopia/server_data.php", handler);
All requests and responses are logged, including:
  • HTTP headers
  • Query parameters
  • Request body
  • Original and modified server data

​
DNS Resolution

The web server uses the DNS resolver configured in the client configuration (src/core/web_server.cpp:22): 
dns_resolver_{ network::create_dns_provider(config_.get_client_config().dns_server) }
See the Configuration File documentation for DNS server options.

​
SSL/TLS Setup

For the HTTPS server to work, you need valid SSL certificates:

​
Certificate Files

Place the following files in the resources/ directory:
  • cert.pem - SSL certificate
  • key.pem - SSL private key

​
Installing the Certificate

The Growtopia client must trust your SSL certificate. This typically involves:
  1. Installing the certificate in your system’s trusted certificate store
  2. Configuring the Growtopia client to accept your certificate
  3. Using a certificate signed by a trusted Certificate Authority (CA)
Never commit or share your private key (key.pem) file. Keep it secure and private.

​
Response Format

The server data response is in a custom text format parsed by utils::TextParse: 
server|growtopia.server.address
port|17091
type|1
type2|1
maint|Server maintenance message (if any)
The web server modifies this to redirect to the local proxy: 
server|127.0.0.1
port|16999
type|1
type2|1
maint|Server maintenance message (if any)

​
Event Integration

The web server listens for client connection events (src/core/web_server.cpp:33-34):
  • ClientConnect: When a client connects to the proxy, the web server initiates a connection to the real Growtopia server
  • ClientDisconnect: When a client disconnects, pending connection data is cleared
This ensures the proxy maintains proper state between the client and server connections.

​
Error Handling

The web server handles various error conditions:
​
500 Internal Server Error
Returned when:
  • DNS resolution fails for the server address
  • TextParse fails to parse the server response
  • Port number parsing fails
​
502 Bad Gateway
Returned when:
  • Cannot connect to the official Growtopia server
  • Official server returns a non-200 HTTP status
  • Server response body is empty
All errors are logged with detailed information using spdlog.

​
Logging

The web server logs all HTTP requests and responses (src/core/web_server.cpp:48-50): 
https_server_.set_logger([](const httplib::Request& req, const httplib::Response& res) {
    spdlog::info("{} {} {}", req.method, req.path, res.status);
});
Additional debug logging includes:
  • Request headers, params, and body
  • Original server_data.php response
  • Modified server_data.php response (when debug logging is enabled)
  • Connection events and errors

​
Port Binding

Binding to port 443 requires administrator/root privileges on most systems:Windows: Run GTProxy as AdministratorLinux/macOS: Run with sudo or use setcap to grant port binding capabilities
sudo ./gtproxy
# or
sudo setcap 'cap_net_bind_service=+ep' ./gtproxy
If the server fails to bind to port 443, an error is logged and the proxy continues without the web server functionality.

Build docs developers (and LLMs) love

Get started for freeTalk to us