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.

​
Introduction

GTProxy features a powerful Lua scripting engine that allows you to extend the proxy’s functionality without modifying the C++ source code. Scripts are loaded automatically from the scripts/ directory at startup and have access to a comprehensive API for packet manipulation, event handling, command registration, and more.

​
Scripting Engine

The scripting engine is built with sol2, a modern C++/Lua binding library that provides:
  • Type-safe C++ to Lua bindings
  • Automatic lifetime management
  • Zero-overhead abstractions
  • Full access to C++ types and functions
GTProxy uses Lua 5.4 as its scripting runtime.

​
Global APIs

Every script has access to these global APIs:
APIPurpose
loggerLogging functions with fmt-style formatting
eventEvent system for packet and connection events
sendSend packet structs to client or server
packetPacket types, enums, and raw send helpers
commandRegister custom proxy commands
schedulerSchedule timed tasks and callbacks
worldAccess world and player state
item_databaseAccess item database for lookups

​
Quick Example

Here’s a simple script that logs when players connect: 
event.on("server:Connect", function(ctx)
    logger.info("Connected to game server!")
end)

event.on("OnSpawn", function(ctx)
    if ctx:has_packet() then
        local pkt = ctx:get_packet()
        logger.info("Player spawned: {}", pkt.name)
    end
end)

​
Script Loading

Scripts are automatically loaded from the scripts/ directory when GTProxy starts. All .lua files in this directory are executed in alphabetical order.
You can organize your scripts into subdirectories - GTProxy will recursively load all .lua files.

​
Error Handling

When a script encounters an error, GTProxy will:
  1. Log the error with a full stack trace
  2. Continue running other scripts
  3. Disable the failed script to prevent repeated errors
Always test your scripts thoroughly before deploying them.

​
Next Steps

Getting Started

Write your first Lua script

API Reference

Explore the complete API

Examples

Learn from real scripts

Build docs developers (and LLMs) love

Get started for freeTalk to us