Add Private Function With Signatures

Overview

This skill guides the process of adding private functions from game engine DLLs to metamod plugins. It covers IDA Pro analysis, signature creation, function type definition, and runtime hooking for both Windows and Linux platforms.

Workflow

Step 1: Analyze Function with IDA Pro

Use IDA Pro MCP tools to analyze the target function:

# Find the function
mcp__ida-pro-mcp__lookup_funcs("FunctionName")

# Get decompiled code
mcp__ida-pro-mcp__decompile("0xAddress")

# Get disassembly
mcp__ida-pro-mcp__disasm("0xAddress", max_instructions=30)

# Extract signature bytes
mcp__ida-pro-mcp__get_bytes({"addr": "0xAddress", "size": 50})

# Verify signature uniqueness (CRITICAL STEP!)
# Convert bytes to IDA search format (use signature_converter.py script)
python scripts/signature_converter.py spaced "\\x83\\xEC\\x2C\\xA1\\x2A\\x2A\\x2A\\x2A"
# Output: 83 EC 2C A1 ?? ?? ?? ??

# Search in IDA Pro with converted pattern
mcp__ida-pro-mcp__find_bytes("83 EC 2C A1 ?? ?? ?? ?? 33 C4")
# Result should show ONLY ONE match - your target function
# If multiple matches found, extend signature or use more specific bytes

Critical: Always verify signature uniqueness using

find_bytes

. If the pattern matches multiple functions, the signature is too generic and must be made more specific.

Tip: Use

scripts/signature_converter.py

to convert between formats:

# Convert C string to IDA format
python scripts/signature_converter.py spaced "\\x83\\xEC\\x2C"

# Convert IDA format to C string
python scripts/signature_converter.py c_string "83 EC 2C"

# Show all formats
python scripts/signature_converter.py all "83EC2C"

Step 2: Define Function Type

Edit

fallguys/serverdef.h

:

// Function signature from IDA: ReturnType __callingconv FunctionName(params)
typedef ReturnType(CALLING_CONVENTION *fnFunctionName)(ParamTypes);
PRIVATE_FUNCTION_EXTERN(FunctionName);

Calling convention mapping:

• SC_SERVER_DECL

  - fastcall (Windows) / cdecl (Linux), for class methods

• SC_SERVER_CDECL

  - cdecl (both platforms), for C functions
• Default - cdecl

For new calling conventions, see calling-conventions.md.

Step 3: Add Function Signatures

Edit

fallguys/signatures.h

:

Windows signature:

#ifdef _WIN32
#define FunctionName_Signature "\\x83\\xEC\\x2C\\xA1\\x2A\\x2A\\x2A\\x2A..."

Linux signature and symbol:

#else
#define FunctionName_Signature "\\x55\\x57\\x56\\x53\\x83\\xEC\\x5C..."
#define FunctionName_Symbol "_Z23FunctionNameMangledName"

See signature-patterns.md for signature creation guidelines.

Step 4: Define Global Function Pointer

Edit

fallguys/server_hook.cpp

(or relevant .cpp file):

PRIVATE_FUNCTION_DEFINE(ExistingFunction1);
PRIVATE_FUNCTION_DEFINE(ExistingFunction2);
PRIVATE_FUNCTION_DEFINE(FunctionName);  // Add new line

This expands to:

fnFunctionName g_pfn_FunctionName;
fnFunctionName g_call_original_FunctionName;

Step 5: Fill Function Pointer in Meta_Attach

Edit

fallguys/meta_api.cpp

:

Windows branch:

#ifdef _WIN32
FILL_FROM_SIGNATURE(server, FunctionName);

Linux Sven Co-op 5.16+ branch:

if (CreateInterface("SCServerDLL003", nullptr) != nullptr)
{
    FILL_FROM_SIGNATURE(server, FunctionName);
}

Linux Sven Co-op 5.15 branch:

else
{
    FILL_FROM_SYMBOL(server, FunctionName);
}

Fill macros:

• FILL_FROM_SIGNATURE(module, name)

  - Scan by signature

• FILL_FROM_SYMBOL(module, name)

  - Lookup by symbol

• FILL_FROM_SIGNATURED_CALLER_FROM_END(module, name, offset)

  - Scan caller signature

Module options:

server

(server.dll/so),

engine

(hw.dll/so)

Step 6: Call Function in Business Code

Always check pointer before calling:

if (g_pfn_FunctionName)
{
    g_pfn_FunctionName(arg1, arg2);
}

Example usage:

ASEXT_RegisterDocInitCallback([](CASDocumentation *pASDoc) {
    if (g_pfn_RegisterSCScriptColor24)
    {
        g_pfn_RegisterSCScriptColor24(pASDoc);
    }
});

Checklist

• Analyze function with IDA Pro (decompile, disasm, bytes)
• Verify signature uniqueness in IDA Pro
• Define calling convention macro (if new) in

  asext/include/asext_api.h

• Define function typedef in

  fallguys/serverdef.h

• Add Windows signature in

  fallguys/signatures.h

• Add Linux signature and symbol in

  fallguys/signatures.h

• Add

  PRIVATE_FUNCTION_DEFINE

  in

  fallguys/server_hook.cpp

• Add Windows

  FILL_FROM_SIGNATURE

  in

  fallguys/meta_api.cpp

• Add Linux 5.16

  FILL_FROM_SIGNATURE

  in

  fallguys/meta_api.cpp

• Add Linux 5.15

  FILL_FROM_SYMBOL

  in

  fallguys/meta_api.cpp

• Call function with null check in business code
• Compile and test (Windows and Linux)
• Verify function found in logs

Key Files

• asext/include/asext_api.h

  - Calling convention macros

• fallguys/serverdef.h

  - Function type definitions

• fallguys/signatures.h

  - Signatures and symbols

• fallguys/server_hook.cpp

  - Function pointer definitions

• fallguys/meta_api.cpp

  - Function pointer filling

• metamod/signatures_template.h

  - Macro definitions

References

• calling-conventions.md - Detailed calling convention guide
• signature-patterns.md - Signature creation best practices
• troubleshooting.md - Common issues and solutions

Scripts

signature_converter.py

Converts between three signature formats:

• C String:

  \x83\xEC\x2C\xA1\x2A

  (for code)
• Spaced:

  83 EC 2C A1 ??

  (for IDA Pro)
• Compact:

  83EC2CA12A

  (compressed)

Usage:

# Convert to IDA Pro format
python scripts/signature_converter.py spaced "\x83\xEC\x2C"

# Convert to C string format
python scripts/signature_converter.py c_string "83 EC 2C"

# Show all formats
python scripts/signature_converter.py all "83EC2C"

# Get help
python scripts/signature_converter.py --help