GameData System

How to use custom gamedata files for signatures, offsets, addresses, patches, and vtables.

Overview

The GameData system allows plugins to access game internals through signatures, offsets, addresses, patches, and vtables. This enables hooking functions, reading memory, and modifying game behavior without hardcoded addresses.

GameData files are JSON-based configuration files that contain platform-specific patterns and offsets. The system automatically handles platform differences (Windows/Linux) and game updates by using signature scanning instead of hardcoded addresses.

Key Benefits:

Platform-independent code (Windows/Linux handled automatically)
Resilient to game updates (signatures auto-locate addresses)
Centralized configuration for memory operations
Automatic binary patching support

API Approaches

The s2sdk provides two ways to work with gamedata:

Functional API - Manual handle management with LoadGameConfigFile / CloseGameConfigFile
Object-Oriented API - RAII wrapper using the GameConfig class (automatic cleanup)

Recommended: Use the GameConfig class for automatic resource management (RAII). It automatically closes the gamedata file when the object is destroyed, preventing memory leaks.

Loading and Closing GameData Files (Functional API)

Use LoadGameConfigFile to load a custom gamedata file and CloseGameConfigFile when done.

Path Array: LoadGameConfigFile takes an array of file paths to search for the gamedata file. To load from your plugin's directory, construct the full path using your plugin's location.

Getting Plugin Location

Each language provides a way to access the plugin's directory:

Language	Method
C#	`this.GetLocation()`
C++	`this->GetLocation()`
Python	`self.location`
Go	`plugify.Plugin.Location`
JavaScript	`this.location`
Lua	`self.location`

c++

python

lua

using Plugify;
using static s2sdk.s2sdk;

public unsafe class Sample : Plugin
{
    private nint gameData;

    public void OnPluginStart()
    {
        // Construct path to gamedata file in plugin directory
        string pluginPath = this.GetLocation();
        string gamedataPath = Path.Combine(pluginPath, "my_gamedata.json");

        // Load gamedata file (requires array of paths)
        gameData = LoadGameConfigFile(new[] { gamedataPath });

        if (gameData == IntPtr.Zero)
        {
            PrintToServer("Failed to load gamedata file!\n");
            return;
        }

        // Use gamedata methods...
        int offset = GetGameConfigOffset(gameData, "SomeOffset");
        PrintToServer($"Offset value: {offset}\n");
    }

    public void OnPluginEnd()
    {
        // Clean up gamedata
        if (gameData != IntPtr.Zero)
        {
            CloseGameConfigFile(gameData);
            gameData = IntPtr.Zero;
        }
    }
}

JSON Schema Structure

GameData files use JSON format with platform-specific configurations. Here's the basic structure:

{
  "Signatures": {
    "SignatureName": {
      "library": "server",
      "win64": "48 89 5C 24 ? 48 89 6C 24 ? 48 89 74 24 ? 57 41 56 41 57 48 83 EC 40",
      "linuxsteamrt64": "55 48 89 E5 41 57 41 56 41 55 41 54 53 48 83 EC 18"
    }
  },
  "Offsets": {
    "OffsetName": {
      "win64": 123,
      "linuxsteamrt64": 456
    }
  },
  "Addresses": {
    "AddressName": {
      "signature": "SignatureName",
      "win64": [
        {
          "offset": 10
        },
        {
          "read": 2
        }
      ],
      "linuxsteamrt64": [
        {
          "offset": 5
        },
        {
          "read": 2
        }
      ]
    }
  },
  "Patches": {
    "PatchName": {
      "address": "SignatureName",
      "win64": "EB",
      "linuxsteamrt64": "90 90"
    }
  },
  "VTables": {
    "VTableName": {
      "library": "server",
      "table": "CBaseEntity"
    }
  }
}

Important: The gamedata file should be placed in your plugin's data directory. The filename passed to LoadGameConfigFile should be relative to that directory.

Using GameConfig Class (Object-Oriented API)

The GameConfig class is a RAII wrapper that automatically manages gamedata resources. It's constructed using LoadGameConfigFile and automatically calls CloseGameConfigFile when destroyed.

Benefits of GameConfig Class:

Automatic resource cleanup (RAII pattern)
No manual CloseGameConfigFile needed
Cleaner, more maintainable code
Type-safe interface with member methods

GameConfig Methods

The GameConfig class provides the following methods:

GetPatch(name) - Get address where a patch was applied
GetOffset(name) - Get a named offset value
GetAddress(name) - Get a resolved address
GetVTable(name) - Get address of a virtual table
GetSignature(name) - Get address of a named signature

c++

python

lua

using Plugify;
using static s2sdk.s2sdk;

public unsafe class Sample : Plugin
{
    private GameConfig? gameConfig;

    public void OnPluginStart()
    {
        // Constructor automatically loads gamedata
        gameConfig = new GameConfig("my_gamedata.json");

        if (gameConfig == null || !gameConfig.IsValid)
        {
            PrintToServer("Failed to load gamedata file!\n");
            return;
        }

        // Use member methods directly on the object
        int offset = gameConfig.GetOffset("SomeOffset");
        PrintToServer($"Offset value: {offset}\n");

        nint signature = gameConfig.GetSignature("SignatureName");
        PrintToServer($"Signature at: 0x{signature:X}\n");

        nint address = gameConfig.GetAddress("GlobalVars");
        PrintToServer($"Address at: 0x{address:X}\n");
    }

    public void OnPluginEnd()
    {
        // Destructor automatically closes gamedata - no manual cleanup needed!
        gameConfig?.Dispose();
        gameConfig = null;
    }
}

Key Difference: With the OOP approach, you don't need to pass the gamedata handle to each method call. The GameConfig object encapsulates the handle and provides member methods that automatically use it.

Signatures

Signatures are byte patterns used to locate functions or data in game binaries. They're resilient to minor game updates.

Signature Format

Signatures use hex bytes with ? as wildcards:

48 89 5C 24 - Exact bytes
? or ?? - Any single byte (wildcard)
Space-separated hex values

Generating Signatures

You can generate signatures using:

IDA Pro with sigmaker plugin
Binary Ninja with signature generation scripts
Ghidra with custom scripts

Signature Naming: If a signature starts with @ (e.g., @FunctionName), the system will treat it as a symbol name instead of a byte pattern. This is useful for exported functions.

Using Signatures

c++

python

// Get single signature
nint address = GetGameConfigSignature(gameData, "SignatureName");
if (address != IntPtr.Zero)
{
    PrintToServer($"Found signature at: 0x{address:X}\n");
}

// Search all loaded configs for signature
nint signatureAll = GetGameConfigSignatureAll("SignatureName");

Offsets

Offsets are numeric values representing memory positions or structure field offsets. They're platform-specific.

Defining Offsets

{
  "Offsets": {
    "HealthOffset": {
      "win64": 3216,
      "linuxsteamrt64": 3240
    },
    "VelocityOffset": {
      "win64": 1024,
      "linuxsteamrt64": 1040
    }
  }
}

Using Offsets

c++

python

// Get single offset
int healthOffset = GetGameConfigOffset(gameData, "HealthOffset");
PrintToServer($"Health offset: {healthOffset}\n");

// Search all loaded configs for offset
int offsetAll = GetGameConfigOffsetAll("HealthOffset");

// Use offset with entity data
int entityHandle = PlayerSlotToEntHandle(0);
SetEntData(entityHandle, healthOffset, 200, 4, true, 0);

Addresses

Addresses combine signatures with offset calculations to locate specific memory positions. They support three resolution types:

Address Types

offset - Add offset to signature address
read - Read pointer at signature + offset, follow N times
read_offs32 - Read 32-bit relative offset, calculate absolute address

Defining Addresses

Addresses are defined as arrays of action steps for each platform:

{
  "Addresses": {
    "GlobalVars": {
      "signature": "GlobalVarsSignature",
      "win64": [
        {
          "offset": 3
        }
      ],
      "linuxsteamrt64": [
        {
          "offset": 3
        }
      ]
    },
    "EntityList": {
      "signature": "EntityListSignature",
      "win64": [
        {
          "offset": 10
        },
        {
          "read": 2
        }
      ],
      "linuxsteamrt64": [
        {
          "offset": 8
        },
        {
          "read": 2
        }
      ]
    },
    "SomeFunction": {
      "signature": "FunctionCallSignature",
      "win64": [
        {
          "read_offs32": 1
        }
      ],
      "linuxsteamrt64": [
        {
          "read_offs32": 1
        }
      ]
    }
  }
}

Step Execution: Each address action is executed sequentially. For example, EntityList first adds offset 10, then reads the pointer 2 times.

Using Addresses

c++

python

// Get single address
nint globalVarsAddr = GetGameConfigAddress(gameData, "GlobalVars");
if (globalVarsAddr != IntPtr.Zero)
{
    PrintToServer($"GlobalVars at: 0x{globalVarsAddr:X}\n");

    // Use the address to read/write memory
    // ... pointer dereferencing code ...
}

// Search all loaded configs for address
nint addressAll = GetGameConfigAddressAll("GlobalVars");

Patches

Patches allow automatic modification of game binaries at runtime. They locate code using signatures and replace bytes.

Warning: Patches modify game memory directly. Incorrect patches can crash the server. Always verify bytes before patching!

Defining Patches

Patches reference an address (from Addresses or Signatures sections) and specify the patch bytes to write:

{
  "Patches": {
    "VScriptEnable": {
      "address": "VScriptInitialization",
      "win64": "BE 02",
      "linuxsteamrt64": "83 FE 02"
    },
    "NoValidation": {
      "address": "ValidationCheck",
      "win64": "EB",
      "linuxsteamrt64": "90 90"
    }
  }
}

address - Name of address/signature from the gamedata file
win64 / linuxsteamrt64 - Hex bytes to write (patch bytes)

Caution: Patches modify game memory directly and are automatically applied on load. Test thoroughly to avoid crashes!

Automatic Application: Patches are automatically applied when the gamedata file is loaded. You don't need to call any functions - the system handles it!

Retrieving Patch Information

While patches are applied automatically, you can still query patch data:

c++

python

// Get single patch address (where it was applied)
nint patchAddr = GetGameConfigPatch(gameData, "DisableValidation");
if (patchAddr != IntPtr.Zero)
{
    PrintToServer($"Patch applied at: 0x{patchAddr:X}\n");
}

// Search all loaded configs for patch
nint patchAll = GetGameConfigPatchAll("DisableValidation");

VTables

Virtual tables (VTables) are used for virtual function lookups in C++ objects. Use them to find function pointers in class vtables.

Defining VTables

{
  "VTables": {
    "CBaseEntity": {
      "signature": "CBaseEntityVTableSignature",
      "offset": {
        "windows": 0,
        "linux": 0
      }
    },
    "CBasePlayer": {
      "signature": "CBasePlayerVTableSignature",
      "offset": {
        "windows": 8,
        "linux": 8
      }
    }
  }
}

Using VTables

c++

python

// Get single vtable
nint vtableAddr = GetGameConfigVTable(gameData, "CBaseEntity");
if (vtableAddr != IntPtr.Zero)
{
    PrintToServer($"CBaseEntity vtable at: 0x{vtableAddr:X}\n");

    // You can now access virtual function pointers
    // vtable[0], vtable[1], etc.
}

// Search all loaded configs for vtable
nint vtableAll = GetGameConfigVTableAll("CBaseEntity");

Complete Example: Custom Gamedata Plugin

Here's a complete example that demonstrates all gamedata features:

c++

python

lua

using System;
using Plugify;
using static s2sdk.s2sdk;

public unsafe class GameDataExample : Plugin
{
    private nint gameData;

    public void OnPluginStart()
    {
        // Load custom gamedata
        gameData = LoadGameConfigFile("example.json");

        if (gameData == IntPtr.Zero)
        {
            PrintToServer("[ERROR] Failed to load gamedata!\n");
            return;
        }

        PrintToServer("=== GameData Loaded Successfully ===\n");

        // Demonstrate Signature
        PrintToServer("\n--- Signature Example ---\n");
        nint signature = GetGameConfigSignature(gameData, "SignatureName");
        PrintToServer($"  Signature: 0x{signature:X}\n");

        // Demonstrate Offset
        PrintToServer("\n--- Offset Example ---\n");
        int offset = GetGameConfigOffset(gameData, "OffsetName");
        PrintToServer($"  Offset: {offset}\n");

        // Demonstrate Address
        PrintToServer("\n--- Address Example ---\n");
        nint addr = GetGameConfigAddress(gameData, "AddressName");
        PrintToServer($"  Address: 0x{addr:X}\n");

        // Demonstrate Patch
        PrintToServer("\n--- Patch Example ---\n");
        nint patchAddr = GetGameConfigPatch(gameData, "PatchName");
        PrintToServer($"  Patch: 0x{patchAddr:X} (auto-applied)\n");

        // Demonstrate VTable
        PrintToServer("\n--- VTable Example ---\n");
        nint vtableAddr = GetGameConfigVTable(gameData, "VTableName");
        PrintToServer($"  VTable: 0x{vtableAddr:X}\n");

        PrintToServer("\n=== GameData Demo Complete ===\n");
    }

    public void OnPluginEnd()
    {
        if (gameData != IntPtr.Zero)
        {
            CloseGameConfigFile(gameData);
            gameData = IntPtr.Zero;
            PrintToServer("GameData closed.\n");
        }
    }
}

#include <plugify/cpp_plugin.hpp>
#include "s2sdk.hpp"

using namespace s2sdk;

class GameDataExample : public plg::IPluginEntry {
private:
    void* gameData = nullptr;

public:
    void OnPluginStart() override {
        // Load custom gamedata
        gameData = LoadGameConfigFile("example.json");

        if (gameData == nullptr) {
            PrintToServer("[ERROR] Failed to load gamedata!\n");
            return;
        }

        PrintToServer("=== GameData Loaded Successfully ===\n");

        // Demonstrate Signature
        PrintToServer("\n--- Signature Example ---\n");
        void* signature = GetGameConfigSignature(gameData, "SignatureName");
        PrintToServer(std::format("  Signature: {:X}\n",
                      reinterpret_cast<uintptr_t>(signature)).c_str());

        // Demonstrate Offset
        PrintToServer("\n--- Offset Example ---\n");
        int offset = GetGameConfigOffset(gameData, "OffsetName");
        PrintToServer(std::format("  Offset: {}\n", offset).c_str());

        // Demonstrate Address
        PrintToServer("\n--- Address Example ---\n");
        void* addr = GetGameConfigAddress(gameData, "AddressName");
        PrintToServer(std::format("  Address: {:X}\n",
                      reinterpret_cast<uintptr_t>(addr)).c_str());

        // Demonstrate Patch
        PrintToServer("\n--- Patch Example ---\n");
        void* patchAddr = GetGameConfigPatch(gameData, "PatchName");
        PrintToServer(std::format("  Patch: {:X} (auto-applied)\n",
                      reinterpret_cast<uintptr_t>(patchAddr)).c_str());

        // Demonstrate VTable
        PrintToServer("\n--- VTable Example ---\n");
        void* vtableAddr = GetGameConfigVTable(gameData, "VTableName");
        PrintToServer(std::format("  VTable: {:X}\n",
                      reinterpret_cast<uintptr_t>(vtableAddr)).c_str());

        PrintToServer("\n=== GameData Demo Complete ===\n");
    }

    void OnPluginEnd() override {
        if (gameData != nullptr) {
            CloseGameConfigFile(gameData);
            gameData = nullptr;
            PrintToServer("GameData closed.\n");
        }
    }
};

local plugify = require 'plugify'
local Plugin = plugify.Plugin
local s2 = require 's2sdk'

local GameDataExample = {}
setmetatable(GameDataExample, { __index = Plugin })

function GameDataExample:new()
    local obj = {}
    setmetatable(obj, { __index = self })
    obj.game_data = nil
    return obj
end

function GameDataExample:plugin_start()
    -- Load custom gamedata
    self.game_data = s2:LoadGameConfigFile("example.json")

    if self.game_data == nil then
        s2:PrintToServer("[ERROR] Failed to load gamedata!\n")
        return
    end

    s2:PrintToServer("=== GameData Loaded Successfully ===\n")

    -- Demonstrate Signature
    s2:PrintToServer("\n--- Signature Example ---\n")
    local signature = s2:GetGameConfigSignature(self.game_data, "SignatureName")
    s2:PrintToServer(string.format("  Signature: 0x%X\n", signature))

    -- Demonstrate Offset
    s2:PrintToServer("\n--- Offset Example ---\n")
    local offset = s2:GetGameConfigOffset(self.game_data, "OffsetName")
    s2:PrintToServer(string.format("  Offset: %d\n", offset))

    -- Demonstrate Address
    s2:PrintToServer("\n--- Address Example ---\n")
    local addr = s2:GetGameConfigAddress(self.game_data, "AddressName")
    s2:PrintToServer(string.format("  Address: 0x%X\n", addr))

    -- Demonstrate Patch
    s2:PrintToServer("\n--- Patch Example ---\n")
    local patch_addr = s2:GetGameConfigPatch(self.game_data, "PatchName")
    s2:PrintToServer(string.format("  Patch: 0x%X (auto-applied)\n", patch_addr))

    -- Demonstrate VTable
    s2:PrintToServer("\n--- VTable Example ---\n")
    local vtable_addr = s2:GetGameConfigVTable(self.game_data, "VTableName")
    s2:PrintToServer(string.format("  VTable: 0x%X\n", vtable_addr))

    s2:PrintToServer("\n=== GameData Demo Complete ===\n")
end

function GameDataExample:plugin_end()
    if self.game_data ~= nil then
        s2:CloseGameConfigFile(self.game_data)
        self.game_data = nil
        s2:PrintToServer("GameData closed.\n")
    end
end

local M = {}
M.GameDataExample = GameDataExample
return M

Method Reference

File Management

Method	Description
`LoadGameConfigFile(filename)`	Load a gamedata JSON file. Returns handle or null on failure.
`CloseGameConfigFile(handle)`	Close and free a gamedata file.

Signatures

Method	Description
`GetGameConfigSignature(handle, name)`	Get address of a named signature from specific config.
`GetGameConfigSignatureAll(name)`	Search all loaded configs for signature.

Offsets

Method	Description
`GetGameConfigOffset(handle, name)`	Get a named offset value from specific config.
`GetGameConfigOffsetAll(name)`	Search all loaded configs for offset.

Addresses

Method	Description
`GetGameConfigAddress(handle, name)`	Get a resolved address from specific config.
`GetGameConfigAddressAll(name)`	Search all loaded configs for address.

Patches

Method	Description
`GetGameConfigPatch(handle, name)`	Get address where patch was applied in specific config.
`GetGameConfigPatchAll(name)`	Search all loaded configs for patch.

Note: Patches are automatically applied when loading gamedata. Use GetGameConfigPatch() to verify patch locations, not to apply them.

VTables

Method	Description
`GetGameConfigVTable(handle, name)`	Get address of a virtual table from specific config.
`GetGameConfigVTableAll(name)`	Search all loaded configs for vtable.

Tips and Best Practices

Always close gamedata files - Use CloseGameConfigFile() in OnPluginEnd() to prevent memory leaks
Validate signatures - Check if returned addresses are not null before using them
Use meaningful names - Name your signatures, offsets, and addresses descriptively
Document your patterns - Comment where signatures came from and what they point to
Test on all platforms - Ensure both Windows and Linux patterns are correct
Keep gamedata updated - Update signatures when game updates break them
Use verify bytes in patches - Always specify verify to prevent incorrect patching
Cache addresses - Store resolved addresses instead of calling Get methods repeatedly
Organize your JSON - Group related signatures, offsets, and addresses together
Version your gamedata - Consider adding version comments to track changes

Troubleshooting

Signature Not Found

Cause: Pattern doesn't match game binary
Solution: Regenerate signature using IDA/Binary Ninja, check platform-specific patterns

Patch Verify Failed

Cause: Game was updated and bytes changed
Solution: Update verify and patch bytes for new game version

Invalid Address Returned

Cause: Signature failed or offset calculation incorrect
Solution: Verify signature works, check offset and read values

Gamedata File Not Loading

Cause: File not found or invalid JSON
Solution: Check file path, validate JSON syntax

Platform Differences: Always test your gamedata on both Windows and Linux. Signatures and offsets often differ between platforms!

Advanced Topics

Symbol-Based Signatures

For exported functions, use @ prefix to reference by symbol name:

{
  "Signatures": {
    "CreateInterface": {
      "windows": {
        "library": "server",
        "signature": "@CreateInterface"
      },
      "linux": {
        "library": "server",
        "signature": "@CreateInterface"
      }
    }
  }
}

Multi-Level Address Resolution

Combine read with offsets to follow pointer chains:

{
  "Addresses": {
    "DeepPointer": {
      "signature": "BaseSignature",
      "win64": [
        {
          "offset": 10
        },
        {
          "read": 3
        }
      ],
      "linuxsteamrt64": [
        {
          "offset": 8
        },
        {
          "read": 3
        }
      ]
    }
  }
}

This first adds the offset, then reads the pointer 3 times (follows 3 pointer dereferences).

Relative Offset Addresses (read_offs32)

Use read_offs32 for RIP-relative addressing (common in x64). This reads a 32-bit relative offset and calculates the absolute address:

{
  "Addresses": {
    "v8::Isolate::Enter": {
      "signature": "CSScript::ResolveModule",
      "win64": [
        {
          "read_offs32": 59
        }
      ],
      "linuxsteamrt64": [
        {
          "read_offs32": 45
        }
      ]
    }
  }
}

This is useful when the signature points to instructions like call [rip + offset] or lea reg, [rip + offset]. The value of read_offs32 is the byte offset where the 32-bit relative offset is located.

With this guide, you now have complete knowledge of the GameData system in s2sdk. Use it to create robust, update-resistant plugins that interact with game internals!

Edit this page on GitHub

Check Transmit

How to control entity visibility and network transmission using CheckTransmit system.

Panorama Voting System

How to create custom Yes/No votes using the Panorama UI system.

On This Page

Star on GitHub Create Issues Become a Sponsor Edit this page on GitHub