Lua Scripting Overview

Extend GTProxy with powerful Lua scripts using sol2 bindings

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:

API	Purpose
logger	Logging functions with fmt-style formatting
event	Event system for packet and connection events
send	Send packet structs to client or server
packet	Packet types, enums, and raw send helpers
command	Register custom proxy commands
scheduler	Schedule timed tasks and callbacks
world	Access world and player state
item_database	Access 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