# ScriptFunction vs Native Function Invocation in YimMenuV2: Key Differences Explained

> Understand ScriptFunction vs native function invocation in YimMenuV2. Learn how to optimize your YimMenu scripts for performance and safety with our clear explanation.

- Repository: [YimMenu/YimMenuV2](https://github.com/YimMenu/YimMenuV2)
- Tags: deep-dive
- Published: 2026-07-17

---

**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`](https://github.com/YimMenu/YimMenuV2/blob/main/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`](https://github.com/YimMenu/YimMenuV2/blob/main/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:

```cpp
// 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

```

```cpp
// 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`](https://github.com/YimMenu/YimMenuV2/blob/main/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`](https://github.com/YimMenu/YimMenuV2/blob/main/src/game/scripting/libraries/ScriptFunction.cpp)** – Implements `ScriptFunction::Invoke` for script-level function calls via the VM
- **[`src/game/scripting/libraries/Natives.cpp`](https://github.com/YimMenu/YimMenuV2/blob/main/src/game/scripting/libraries/Natives.cpp)** – Registers and invokes native functions through `Natives::Invoke` 
- **[`src/game/scripting/libraries/Invoker.cpp`](https://github.com/YimMenu/YimMenuV2/blob/main/src/game/scripting/libraries/Invoker.cpp)** – Provides common utilities for building argument packs used by both invocation types
- **[`src/core/scripting/libraries/Script.cpp`](https://github.com/YimMenu/YimMenuV2/blob/main/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`](https://github.com/YimMenu/YimMenuV2/blob/main/ScriptFunction.cpp) and [`Natives.cpp`](https://github.com/YimMenu/YimMenuV2/blob/main/Natives.cpp) while sharing argument packing utilities in [`Invoker.cpp`](https://github.com/YimMenu/YimMenuV2/blob/main/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`](https://github.com/YimMenu/YimMenuV2/blob/main/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.