# How YimMenuV2's Network Module Handles Scripted Game Events (ScriptEvent)

> Discover how YimMenuV2's network module handles scripted game events ScriptEvent by validating and dispatching them via _SEND_TU_SCRIPT_EVENT_NEW.

- Repository: [YimMenu/YimMenuV2](https://github.com/YimMenu/YimMenuV2)
- Tags: internals
- Published: 2026-07-16

---

**YimMenuV2 processes Lua script events by validating arguments, packing them into a fixed 40-slot buffer, and dispatching them through the native GTA V function `_SEND_TU_SCRIPT_EVENT_NEW`.**

The YimMenuV2 GTA V mod menu exposes low-level network scripting capabilities to Lua through its Network library. When developers need to trigger in-game script events—also known as **TU Script Events**—the module bridges the high-level Lua API with the game's native scripting engine. This article examines the exact implementation in [`src/game/scripting/libraries/Network.cpp`](https://github.com/YimMenu/YimMenuV2/blob/main/src/game/scripting/libraries/Network.cpp) to show how `trigger_script_event` marshals data from Lua scripts into the GTA V network layer.

## The trigger_script_event Implementation

The `trigger_script_event` function serves as the primary interface for firing scripted game events. Located in [`src/game/scripting/libraries/Network.cpp`](https://github.com/YimMenu/YimMenuV2/blob/main/src/game/scripting/libraries/Network.cpp), this function accepts an event hash, a player bitmask, a format string, and variable arguments before constructing the native event packet.

### Argument Parsing and Validation

The function begins by extracting three mandatory parameters from the Lua stack. It retrieves the **event hash** (first argument), the **target player mask** (second argument), and the **format string** (third argument) that describes subsequent argument types.

```cpp
auto hash = GetHashArgument(state, 1);
int bits = luaL_checkinteger(state, 2);
auto param_str = CheckStringSafe(state, 3, &param_length);

```

The implementation enforces a strict safety limit: the format string cannot exceed **37 characters**. This ensures the total argument count stays within the fixed 40-slot buffer (3 header slots + 37 payload slots). If `param_length >= 37`, the function raises a Lua error immediately.

### Buffer Preparation and Format String Processing

The module allocates a fixed-size array `int64_t tse_args[40]` on the stack and populates the first three indices with header metadata:

- `tse_args[0]` = Event hash identifier
- `tse_args[1]` = Sender player ID from `Self::GetPlayer().GetId()`
- `tse_args[2]` = Target player bitmask

```cpp
int64_t tse_args[40];
tse_args[0] = hash;
tse_args[1] = Self::GetPlayer().GetId();
tse_args[2] = bits;

```

The function then iterates through the format string to convert Lua arguments into raw 64-bit integers. Each character in the format string dictates the conversion type:

- **`i`** – Integer: Cast to `int64_t`
- **`f`** – Float: Reinterpret-cast to `int64_t`
- **`l`** – Long (64-bit): Stored directly
- **`h`** – Hash (32-bit): Reinterpret-cast to `int64_t`

The loop reads corresponding Lua arguments starting at stack index 4 and packs them into `tse_args[3 + i]`:

```cpp
for (int i = 0; i < param_length; ++i) {
    switch (param_str[i]) {
        case 'i':
            int as_int = luaL_checkinteger(state, 4 + i);
            tse_args[3 + i] = *(int64_t*)&as_int;
            break;
        case 'f':
            float as_float = luaL_checknumber(state, 4 + i);
            tse_args[3 + i] = *(int64_t*)&as_float;
            break;
        // ... cases for 'l' and 'h' follow similar patterns
    }
}

```

### Native Event Transmission

Once the buffer is fully populated, the module invokes the native GTA V function `SCRIPT::_SEND_TU_SCRIPT_EVENT_NEW`. This call propagates the event to the game engine with the calculated argument count (`3 + param_length`), the player bitmask, and the original event hash.

```cpp
SCRIPT::_SEND_TU_SCRIPT_EVENT_NEW(1, tse_args, 3 + param_length, bits, hash);

```

The function returns 0 to Lua, indicating completion without return values.

## Helper Functions in the Network Library

Beyond event triggering, the Network module exposes additional utilities for script manipulation and session state queries.

### force_script_host and force_script_on_player

The `force_script_host` function allows Lua scripts to seize control of a specific script thread, while `force_script_on_player` forces script execution on a targeted player mask. These functions interface with the underlying script management system in [`src/game/gta/Scripts.cpp`](https://github.com/YimMenu/YimMenuV2/blob/main/src/game/gta/Scripts.cpp).

### is_session_started

This utility returns the current session state by dereferencing `*Pointers.IsSessionStarted`, enabling scripts to verify network connectivity before attempting event transmission.

## Practical Usage Examples

### Triggering a Custom Script Event from Lua

```lua
-- Send a script event with integer and float arguments
local eventHash = 0x12345678
local playerBits = -1  -- Broadcast to all players
local format = "if"    -- i = integer, f = float

network.trigger_script_event(eventHash, playerBits, format, 42, 3.14)

```

### Forcing Script Execution on Specific Players

```lua
local scriptHash = 0xDEADBEEF
local targetPlayers = 0x2  -- Player index 2
network.force_script_on_player(scriptHash, targetPlayers)

```

### Checking Session Status

```lua
if network.is_session_started() then
    print("Session active - safe to transmit events")
else
    print("No active session")
end

```

## Key Source Files

The network scripting implementation spans several critical files in the YimMenuV2 codebase:

- **[`src/game/scripting/libraries/Network.cpp`](https://github.com/YimMenu/YimMenuV2/blob/main/src/game/scripting/libraries/Network.cpp)** – Implements `trigger_script_event`, `force_script_host`, `force_script_on_player`, and `is_session_started`
- **[`src/game/gta/Scripts.cpp`](https://github.com/YimMenu/YimMenuV2/blob/main/src/game/gta/Scripts.cpp)** – Provides `FindScriptThread` and `ForceScriptHost` utilities used by network helpers
- **[`src/game/backend/Self.cpp`](https://github.com/YimMenu/YimMenuV2/blob/main/src/game/backend/Self.cpp)** – Retrieves the local player object for sender ID population
- **[`src/core/scripting/LuaLibrary.hpp`](https://github.com/YimMenu/YimMenuV2/blob/main/src/core/scripting/LuaLibrary.hpp)** – Base class handling registration of network functions to the global Lua table

## Summary

- **YimMenuV2** exposes scripted game events through the `network.trigger_script_event` Lua binding implemented in [`Network.cpp`](https://github.com/YimMenu/YimMenuV2/blob/main/Network.cpp).
- The module validates a maximum of 37 payload arguments to prevent buffer overflows in the fixed 40-slot array.
- Format specifiers (`i`, `f`, `l`, `h`) control how Lua values are reinterpret-cast and packed into 64-bit integer slots.
- Events dispatch through the native `SCRIPT::_SEND_TU_SCRIPT_EVENT_NEW` function after populating headers with the event hash, sender ID, and player bitmask.
- Additional utilities like `force_script_host` and `is_session_started` provide comprehensive control over GTA V's network scripting environment.

## Frequently Asked Questions

### What is the maximum number of arguments allowed in trigger_script_event?

The function accepts up to **37 additional arguments** beyond the three header values. This limitation exists because the internal `tse_args` buffer holds exactly 40 slots, with indices 0-2 reserved for the event hash, sender ID, and player bitmask. Exceeding this limit triggers a Lua error.

### How does YimMenuV2 convert Lua types to GTA V script event arguments?

The format string parameter defines the conversion strategy. Integers (`i`) and longs (`l`) cast directly to `int64_t`, while floats (`f`) and hashes (`h`) use reinterpret-cast to preserve bit patterns during the 64-bit packing process. This ensures compatibility with the game's native expectations regardless of Lua's dynamic typing.

### Can script events target specific players or only broadcast to everyone?

The `bits` parameter accepts a player mask allowing precise targeting. Passing `-1` broadcasts to all players, while specific bitmasks target individual player indices. This mechanism integrates directly with GTA V's native networking layer through the `_SEND_TU_SCRIPT_EVENT_NEW` call.

### Where does the Network library register its functions for Lua access?

All network functions register during library initialization through the `Register` method defined in [`LuaLibrary.hpp`](https://github.com/YimMenu/YimMenuV2/blob/main/LuaLibrary.hpp). This binds `trigger_script_event`, `force_script_host`, `force_script_on_player`, and `is_session_started` to the global `network` table available to YimMenuV2 Lua scripts.