ScriptFunction vs Native Function Invocation in YimMenuV2: Key Differences Explained

Script functions execute within GTA V's script VM with bytecode interpretation and safety checks, while native functions call compiled C/C++ code directly through the native handler table for maximum performance.

YimMenuV2 interacts with GTA V through two distinct execution paths that determine how menu features manipulate the game world. Understanding the difference between ScriptFunction and native function invocation is essential for developers working with this open-source mod menu, as each method serves specific use cases within the src/game/scripting/libraries/ architecture and offers unique trade-offs in speed, safety, and capability.

Core Architectural Differences

Script Functions (Script-Level Execution)

Script functions operate within GTA V's built-in scripting engine as bytecode instructions interpreted by the script VM. When invoking a script function, YimMenuV2 resolves the target through scrEngine::GetFunctionByHash, which calculates the hash from the function name using the game's internal algorithm. This lookup occurs in src/game/scripting/libraries/ScriptFunction.cpp, specifically within the ScriptFunction::Invoke wrapper.

The invocation path scrEngine::Invoke(scriptHandle, functionHash, args…) creates a new script stack frame where the VM performs comprehensive type-checking and range validation before executing the script bytecode. This makes script functions inherently safer but introduces interpretation overhead.

Native Functions (Direct C/C++ Calls)

Native functions bypass the script VM entirely, jumping directly to compiled C/C++ implementations exposed through the game's native-handler table. According to the YimMenuV2 source code in src/game/scripting/libraries/Natives.cpp, natives are resolved via NativeRegistry::GetNative using their registered hash (e.g., 0x9BF571D8).

The invocation path native::Invoke(nativeHash, args…) performs lightweight argument count validation before executing the native code. This direct jump minimizes overhead but defers input validation to the native implementation itself, requiring careful argument preparation when calling through Natives::Invoke.

Performance and Safety Characteristics

Script Function Performance

• Slower execution due to VM interpretation, stack frame creation, and bytecode processing
• Comprehensive safety checks including automatic type-checking and range-checking on each argument
• Returns scrEngine::Result indicating script-level exceptions or success status

Native Function Performance

• Faster execution with minimal overhead between the menu and game code
• Lightweight argument count checking only; validation deferred to the native implementation
• Returns boolean or integer status codes; errors typically surface as log messages rather than structured exceptions

Practical Implementation Examples

The following examples demonstrate how YimMenuV2 utilizes both invocation methods in practice:

// Script Function: Invoking a custom script-level spawn function
// Located in: src/game/scripting/libraries/ScriptFunction.cpp
Hash spawnPedHash = 0xA1B2C3D4;
scrEngine::Invoke(CurrentScriptHandle, spawnPedHash,
                  "s_m_y_cop_01",                    // model name
                  Vector3{100.0f, 200.0f, 30.0f});   // spawn position

// Native Function: Direct call to SET_ENTITY_COORDS
// Exposed via: src/game/scripting/libraries/Natives.cpp
Hash setCoordsNative = 0x06843DA7060A026B;
NativeInvoke(setCoordsNative,
             pedHandle,                 // Entity to move
             100.0f, 200.0f, 30.0f,     // x, y, z coordinates
             true, false, false, true); // teleport flags

Mixed usage patterns allow script functions to internally invoke natives while exposing a higher-level API to the menu's C++ core, leveraging src/game/scripting/libraries/Invoker.cpp for shared argument packing utilities.

Source File Architecture

YimMenuV2 organizes these invocation paths across several key files that form the bridge between the menu and GTA V:

• src/game/scripting/libraries/ScriptFunction.cpp – Implements ScriptFunction::Invoke for script-level function calls via the VM
• src/game/scripting/libraries/Natives.cpp – Registers and invokes native functions through Natives::Invoke
• src/game/scripting/libraries/Invoker.cpp – Provides common utilities for building argument packs used by both invocation types
• src/core/scripting/libraries/Script.cpp – Manages script lifecycle, creation, and exposes functions callable from the menu core

Summary

• ScriptFunction calls execute within GTA V's script VM, offering safety through type-checking but incurring interpretation overhead
• Native function invocation bypasses the VM for direct C/C++ execution, prioritizing speed over built-in validation
• Use script functions when accessing script-local variables or custom injected scripts; use natives for low-level game manipulation requiring maximum performance
• The implementation in YimMenuV2 separates these concerns between ScriptFunction.cpp and Natives.cpp while sharing argument packing utilities in Invoker.cpp

Frequently Asked Questions

Can I call native functions from within a script function in YimMenuV2?

Yes. Custom scripts injected by the menu can internally invoke native functions using the standard native invocation pattern. When the script VM encounters a native call during bytecode execution, it transitions from script interpretation to native code execution through native::Invoke before returning to the script context.

Why are native function calls faster than ScriptFunction calls in GTA V modding?

Native function calls use native::Invoke to jump directly to compiled C/C++ code with minimal overhead, while ScriptFunction calls require the script VM to interpret bytecode, manage stack frames, and perform validation checks through scrEngine::Invoke as implemented in YimMenuV2's scripting libraries.

How does YimMenuV2 handle errors differently between these two invocation types?

Script functions return a scrEngine::Result structure that captures script-level exceptions and validation failures, while native invocations return simple boolean or integer status codes. Native errors typically propagate as log messages rather than structured exceptions, requiring developers to check return values manually when using Natives::Invoke from src/game/scripting/libraries/Natives.cpp.

When should I use ScriptFunction instead of native invocation?

Use ScriptFunction when you need to interact with script-local variables, trigger custom scripts injected into the game (such as user-defined spawn logic), or when you require the automatic type-checking provided by the script VM. Use native invocation for direct access to built-in game functions like SET_ENTITY_COORDS or GIVE_WEAPON_TO_PED where execution speed is critical and you can manage argument validation manually.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}