Game Dev

Mod GTA V with C#

By Mony Dragon · Published 2026-11-17

Beginner · 7 days, about an hour a day

GTA VC#moddingScriptHookVDotNetgame devsingle-player

Video walkthrough coming soon — it will appear here once it is published on YouTube.

Your edition

The C# code in this guide is identical for both editions — only the downloads and version numbers change. Pick yours:

Game executable
GTA5_Enhanced.exe
Game build
1.0.1158.13
Script Hook V
v1158.13
.NET host
Script Hook V .NET Enhanced v1.1.0.6

On dev-c.com, pick the Enhanced build — the Legacy build on the same page will not load in an Enhanced install.

A working path from zero to shipping your own single-player mods: install the toolchain, write your first script in Visual Studio, learn the handful of concepts every mod is built from, then climb a ladder of projects that ends with mods worth releasing. Everything here covers both PC editions of GTA V — Legacy and Enhanced — and the C# code is the same for both.

01 — The Stack

Four tools, four jobs.

GTA V has no official mod support. The community built a chain instead: a loader that gets code into the game, a .NET bridge that lets you write that code in C#, an editor to write it in, and a file tool for the game's assets. Everything is free. One thing to know up front: since 2025 the PC game comes in two separate editions — the original Legacy and the upgraded Enhanced — and their tools are not interchangeable. Pick your edition at the top of this page and every version number below follows it.

LegacyEnhanced
Game executableGTA5.exeGTA5_Enhanced.exe
Game build1.0.3889.01.0.1158.13
Script Hook V buildv3889.0v1158.13
Download sourcedev-c.com (Legacy build)dev-c.com (Enhanced build)
.NET hostScript Hook V .NET Enhanced v1.1.0.6Script Hook V .NET Enhanced v1.1.0.6
C# code in this guideStandard SHVDN v3Standard SHVDN v3 — identical
The loader — Script Hook V
Alexander Blade's library, in the build for your edition. It hooks into the game and runs script plugins. The current builds are v1158.13 for Enhanced (matching game build 1.0.1158.13) and v3889.0 for Legacy — a different download per edition, and the wrong one will not work in your install. It also decides your modding calendar: after every GTA V title update, mods break until a new Script Hook V build ships — usually within days. Free — dev-c.com.
The C# bridge — Script Hook V .NET Enhanced
An ASI plugin that hosts the .NET runtime inside the game and wraps the game's native functions in clean C# classes — Ped, Vehicle, World, Game. It's an extended build of ScriptHookVDotNet (SHVDN) that runs on both Legacy and Enhanced with the same API v3 — so every line of code in this guide is standard SHVDN v3, unchanged. Current version v1.1.0.6 (14 Jul 2026). One version trap, flagged again in setup: upstream SHVDN's stable v3.6.0 and v3.5.1 clash with game builds 1.0.3258.0 and later, so where an upstream build is needed, use nightly v3.6.0-nightly.89 or newer until stable v3.7.0 lands. Free, open source — GitHub.
The editor — Visual Studio 2022
The Community edition is free and is what the whole ecosystem assumes. You'll create a .NET Framework 4.8 class library, reference the ScriptHookVDotNet DLL, and build straight into the game's scripts folder. Visual Studio 2026 Community works the same way if that's what you already have installed. Free — Community edition.
The asset tool — OpenIV
Opens GTA V's archive files (.rpf) so you can install or make vehicle, weapon, and texture mods. Not needed for pure C# scripting — and heads-up, OpenIV was built for Legacy and its Enhanced support is still catching up, so the C# path in this guide deliberately never depends on it. Free — openiv.com.

02 — Setup

Install in this order.

About 30–45 minutes, most of it download time. Do it in order — each layer depends on the one before it.

  1. Step 1 — Back up a clean game

    Before anything else, note where GTA V is installed (find GTA5_Enhanced.exe for Enhanced, or GTA5.exe for Legacy — that's your game root folder, and almost everything below happens there). If you have the disk space, copy the whole folder somewhere safe. A clean backup turns every future mistake into a 10-minute restore instead of a 100 GB re-download.

  2. Step 2 — Install Script Hook V

    Download Script Hook V from dev-c.com and pick the build for your edition — currently v1158.13 for Enhanced (matched to game build 1.0.1158.13) or v3889.0 for Legacy. The other build sits on the same page and is the classic wrong download; it will not load in your install. Copy three files from its bin folder into your game root: dinput8.dll (the ASI loader), ScriptHookV.dll, and NativeTrainer.asi (a sample trainer you can delete later). Launch the game and press F4 — if a trainer menu opens, the loader works.

  3. Step 3 — Install Script Hook V .NET Enhanced

    Grab Script Hook V .NET Enhanced v1.1.0.6 from its GitHub releases or its GTA5-Mods.com page. It's a drop-in extension of SHVDN that runs the same scripts on Legacy and Enhanced, so the file names are the familiar ones: copy ScriptHookVDotNet.asi, ScriptHookVDotNet2.dll, ScriptHookVDotNet3.dll, ScriptHookVDotNet.ini, and MinHook.x64.dll (required since v1.1.0.0) into the game root (same folder as your game exe). Install .NET Framework 4.8 and the Visual C++ Redistributable for Visual Studio 2019 (x64) first if they aren't already on your machine — the .NET host needs both. Then create a folder named scripts in the game root — that's where your compiled mods will live.

    Game folder layouttext

    Grand Theft Auto V Enhanced/
    ├─ GTA5_Enhanced.exe
    ├─ dinput8.dll ← Script Hook V Enhanced
    ├─ ScriptHookV.dll ← Script Hook V Enhanced v1158.13
    ├─ ScriptHookVDotNet.asi ← the .NET host (Enhanced)
    ├─ ScriptHookVDotNet3.dll ← the API you reference
    └─ scripts/ ← YOUR mods go here (.dll)
  4. Step 4 — Install Visual Studio 2022

    Install the free Community edition and tick the .NET desktop development workload in the installer. That workload includes the .NET Framework 4.8 targeting pack, which is the exact runtime ScriptHookVDotNet v3 scripts are built against.

  5. Step 5 — Create the project

    In Visual Studio: Create a new project → Class Library (.NET Framework), target .NET Framework 4.8, and set the platform to x64 (the game is 64-bit; an AnyCPU/x86 build won't load). Then right-click the project → Add → Reference → browse to ScriptHookVDotNet3.dll in your game root and add it. Set its Copy Local property to False — the game already has that DLL, and a second copy in scripts causes conflicts.

  6. Step 6 — Build straight into the game

    In the project's properties, set the Output path to your game's scripts folder. Now every Ctrl+Shift+B drops your mod DLL directly where the game loads it. To test changes without restarting GTA V, press F4 in-game to open the ScriptHookVDotNet console and type Reload() — it rebuilds the script list from disk on the spot.

03 — First Mod

Anatomy of a C# mod.

Every ScriptHookVDotNet mod is one class that inherits from Script. You don't write a Main() — the host creates your class, and from then on you live inside events it raises. This is the smallest useful mod: press F5, get a notification.

HelloLosSantos.cscsharp

using System;
using System.Windows.Forms;
using GTA;
using GTA.UI;

public class HelloLosSantos : Script
{
    public HelloLosSantos()
    {
        Tick += OnTick;      // subscribe to the per-frame event
        KeyUp += OnKeyUp;    // subscribe to keyboard events
        Interval = 0;        // 0 = run Tick every frame
    }

    private void OnTick(object sender, EventArgs e)
    {
        // Runs every frame while the game runs.
        // Anything continuous — checks, timers, AI — lives here.
    }

    private void OnKeyUp(object sender, KeyEventArgs e)
    {
        if (e.KeyCode == Keys.F5)
        {
            Notification.Show("Hello from your first mod!");
        }
    }
}
: Script
Inheriting from Script is the whole entry point. The host scans your DLL, finds every Script subclass, and instantiates it. No registration, no manifest.
Tick
The heartbeat. Fires once per frame (or every Interval milliseconds). Keep it fast — a slow Tick is a slow game, because your code runs on the game's own thread.
KeyUp / KeyDown
Standard WinForms key events. KeyUp is usually the right choice for toggles: it fires once per press, not repeatedly while held.
GTA.UI.Notification
The little pop-up feed above the minimap. Screen.ShowSubtitle() is its sibling — text at the bottom of the screen. These two are your debugging console while learning.

Now make it do something: spawn a car.

Same skeleton, one new idea — the World class creates things. World.CreateVehicle handles requesting and loading the model for you, so this is the whole mod. Press F6 anywhere and an Adder appears six meters in front of you.

SpawnAdder.cscsharp

using System.Windows.Forms;
using GTA;
using GTA.Math;
using GTA.UI;

public class SpawnAdder : Script
{
    public SpawnAdder()
    {
        KeyUp += OnKeyUp;
    }

    private void OnKeyUp(object sender, KeyEventArgs e)
    {
        if (e.KeyCode != Keys.F6) return;

        Ped player = Game.Player.Character;
        Vector3 spawnPos = player.Position + player.ForwardVector * 6f;

        Vehicle car = World.CreateVehicle(VehicleHash.Adder, spawnPos, player.Heading);
        if (car == null)
        {
            Notification.Show("Couldn't spawn that vehicle.");
            return;
        }

        car.PlaceOnGround();
        Notification.Show("One Adder, delivered.");
    }
}

Build it, walk into Los Santos, press F6. You've just used the four objects you'll spend 90% of your modding life with: Game.Player (who you are), Ped (any character), Vector3 (positions and directions), and World (the factory for everything). Swap VehicleHash.Adder for any other hash — Buzzard, Rhino, Oppressor2 — and it's a different mod.

04 — Core Concepts

The six ideas behind every mod.

Master these and you can read almost any open-source GTA V mod on GitHub — which is the fastest way to keep learning after this page.

Tick & the game loop
Your script shares the game's thread. Tick fires per frame; anything that must "always be true" (a bodyguard following, a speedometer drawing) is checked there. Count frames or check Game.GameTime instead of sleeping.
Wait() — yielding
Inside a loop, Wait(0) hands control back so the game can render a frame. A while loop without it freezes GTA V solid, because the game is waiting on you. Rule of thumb: every loop in a mod either finishes instantly or calls Wait().
Entities & handles
Ped, Vehicle, and Prop all derive from Entity — they share Position, Heading, Health, Delete(), and Exists(). Always check Exists() before using something you spawned earlier; the game despawns things on its own.
Models load async
The game streams models in on demand. World.CreateVehicle/CreatePed wait for the model for you, but for manual work: create a Model, call Request(), and loop with Wait(0) until IsLoaded — otherwise you spawn nothing, or crash.
Natives
Underneath the friendly classes sit ~6,000 raw game functions called natives. When the C# wrapper doesn't expose something, call it directly with Function.Call. The NativeDB and the FiveM native reference are how you find them and their arguments.
.ini settings
ScriptSettings reads an .ini file with the same name as your DLL from the scripts folder. It's how real mods let players remap keys and tune values without recompiling — and how you'll configure your own mods while testing.

Yielding + a raw native callcsharp

// Throttle Tick work: only run the expensive check ~once a second.
private int tickCount;

private void OnTick(object sender, EventArgs e)
{
    tickCount++;
    if (tickCount % 60 != 0) return;  // ~60 frames ≈ 1 second
    // slow checks go here
}

// A raw native, for when there's no C# wrapper:
// IS_WAYPOINT_ACTIVE — is a purple waypoint set on the map?
bool hasWaypoint = Function.Call<bool>(Hash.IS_WAYPOINT_ACTIVE);

// The loop rule: never spin without yielding a frame.
while (car.Speed < 10f)
{
    Wait(0);  // let the game breathe, or it freezes
    if (!car.Exists()) break;
}

05 — Example Mods

Three more mods, three new skills.

Each of these is a complete, working script. Drop one class per project (or several classes in one project — the host loads them all), build, and test. Read them top to bottom; every line earns its place.

Bodyguard.cscsharp

using System.Windows.Forms;
using GTA;
using GTA.UI;

public class Bodyguard : Script
{
    private Ped guard;

    public Bodyguard()
    {
        KeyUp += OnKeyUp;
    }

    private void OnKeyUp(object sender, KeyEventArgs e)
    {
        if (e.KeyCode != Keys.F7) return;

        Ped player = Game.Player.Character;

        // Second press dismisses him.
        if (guard != null && guard.Exists())
        {
            guard.Delete();
            guard = null;
            Notification.Show("Bodyguard dismissed.");
            return;
        }

        guard = World.CreatePed(new Model("s_m_m_security_01"),
            player.Position + player.ForwardVector * 3f);

        guard.Weapons.Give(WeaponHash.CarbineRifle, 9999, true, true);
        guard.Armor = 100;

        // Put him in the player's group and the game's own AI
        // makes him follow you and fight your fights.
        PedGroup group = player.CurrentPedGroup;
        group.Add(guard, false);
        group.SeparationRange = 15f;

        Notification.Show("Bodyguard on duty. F7 dismisses him.");
    }
}

What it teaches: keeping state between key presses in a field, toggle logic, ped groups — and the big lesson of GTA modding: you rarely script behavior yourself. You set up entities and relationships, and the game's AI does the rest. Change the model string and the weapon hash and he's anyone, armed with anything.

06 — Project Ladder

Five mods that teach you everything.

Build them in order. Each one is a real, releasable mod type — trainers, bodyguards, and heist-style missions are what the GTA V mod scene actually downloads — and each adds exactly one or two new skills.

  1. Step 1 — Personal trainer menu

    Grow Pocket Tools into a real trainer: god mode toggle, never wanted, fix current vehicle, full health and armor. Every feature is a one-liner property set — the skill is organizing toggles that Tick has to keep enforcing (god mode is really "set IsInvincible and re-apply if the game clears it").

    Tick enforcement · toggles · .ini config

  2. Step 2 — Bodyguard squad

    Extend the bodyguard example to a squad of three with different weapons and models, plus a "regroup" key that teleports stragglers to you. Handle the edge cases: guards dying, getting stuck, entering vehicles when you do (SetIntoVehicle).

    Ped groups · collections · entity lifecycle

  3. Step 3 — Custom garage spawner

    A menu of your favorite vehicles defined in the .ini, spawned tuned: pick color, extras, livery, and a license plate. Learn Vehicle.Mods — the customization API — and save the player's current car back into the config.

    Vehicle mods API · data-driven design · menus

  4. Step 4 — Street race

    Checkpoint markers on a route, a countdown, AI opponents driving the same checkpoints (Task.DriveTo), live position tracking, and a finish time on screen. This is the first mod that needs real Tick architecture: a small state machine — waiting, countdown, racing, finished.

    State machines · tasks · blips & markers · HUD text

  5. Step 5 — Mini-heist mission

    The capstone: go to a location, fight waves of guards, grab a briefcase prop, escape to a drop-off while wanted stars climb. Combines spawning, combat AI, objectives, subtitles as mission text, and a payout. If you can build this, you can build nearly any single-player mod — this is the portfolio piece you'd release on GTA5-Mods.com.

    Everything above · mission structure · polish & release

On menus: rungs 3–5 get much nicer with a real menu UI. The ecosystem standard is LemonUI (the maintained successor to NativeUI) — a free C# library that drops into your project the same way ScriptHookVDotNet did, and gives you NativeMenu pools, items, and checkboxes with a few lines of code.

07 — Debugging

When it doesn't work.

Your two best friends: ScriptHookVDotNet.log in the game root (every script error lands there with a stack trace) and the in-game console (F4 → Reload()). Work this list top to bottom — it covers nearly every beginner failure.

SymptomFix
Mod doesn't load at all, no errorCheck the build first: project targets .NET Framework 4.8 and x64, and the DLL actually landed in scripts. Then check versions: Script Hook V must be the build for your edition matching your game build (v1158.13 for Enhanced 1.0.1158.13, v3889.0 for Legacy 1.0.3889.0), and after a title update, nothing loads until it updates.
"Failed to load" in ScriptHookVDotNet.logUsually a reference problem: you referenced the v2 DLL in a v3 project (or vice versa), or left Copy Local on for ScriptHookVDotNet3.dll so a stray copy sits in scripts. Delete the stray copy.
Game freezes solid when the mod runsAn unyielded loop. Somewhere a while/for loop runs long without Wait(0) — most often a "wait until model loads" or "wait until close enough" loop. Add the yield; also add an exit condition so a despawned entity can't trap you forever.
Nothing spawns, or spawns invisibleThe model never loaded. If you're creating entities manually instead of through World.Create*, you must Request() the model and wait for IsLoaded. Also verify the model name/hash — a typo'd string model silently produces nothing.
Script crashes after a while of playingA stale entity. The game despawned something your mod still holds. Guard every stored Ped/Vehicle with Exists() before use, and expect null from spawn calls under memory pressure.
Keys don't respondCheck the obvious: did you subscribe in the constructor (KeyUp += OnKeyUp)? Is another mod or the ScriptHookVDotNet console eating the key (F4 is the console itself)? Were you typing in a game menu? Then try a different key — some are reserved by the game.
"Unknown game version" or a critical error at launchWrong build for your edition or game version. On Enhanced this is almost always one of three things: the Legacy Script Hook V (v3889.0) copied into the Enhanced folder instead of Enhanced v1158.13; the game patched past the hook's build; or an upstream SHVDN stable (v3.6.0 / v3.5.1) running against game 1.0.3258.0+ — switch to the .NET Enhanced build, or nightly v3.6.0-nightly.89+ until stable v3.7.0.
It worked yesterday, broken todayThe game updated. Rockstar patches GTA V, ScriptHookV stops matching, and every script mod is down until a new ScriptHookV build drops. This is normal, expected, and not your code. Serious modders keep the game from auto-updating before a release day.

08 — Your First Week

A 7-day starter plan.

Roughly an hour a day. By day 7 you've shipped something small and real, and you know whether you want to climb the ladder.

  1. Step 1 — Install everything

    Script Hook V (the build for your edition), Script Hook V .NET Enhanced, Visual Studio. End the day with F4 opening the trainer in-game.

  2. Step 2 — Hello, Los Santos

    Build the two mods from this page. Change keys, messages, and the spawned vehicle until the code feels like yours.

  3. Step 3 — Break things on purpose

    Spawn 20 Rhinos. Teleport mid-fall. Dismiss a bodyguard who doesn't exist. Read the log after every crash — that's the curriculum.

  4. Step 4 — Bodyguard squad

    Ladder rung 2. Three guards, different weapons, regroup key.

  5. Step 5 — Read someone else's mod

    Pick a small open-source mod on GitHub and read it end to end. You'll recognize every pattern from this page.

  6. Step 6 — Add a menu

    Install LemonUI and put your trainer features behind a proper menu instead of five hotkeys.

  7. Step 7 — Ship rung 1

    Package your trainer: DLL + .ini + a short readme. Post it on GTA5-Mods.com and your Discord. First release done.

09 — Resources

Bookmark these.

  • ScriptHookV — dev-c.com

    The loader itself, from Alexander Blade. Check here first after every game update.

  • Script Hook V .NET Enhanced — GitHub

    The .NET host for your install: SHVDN extended to run on Legacy and Enhanced with one build. Also on GTA5-Mods.com.

  • ScriptHookVDotNet — GitHub

    The upstream project SHVDNE extends: source, releases, nightly builds, wiki, and the issue tracker. Reading the source is an education by itself.

  • NativeDB

    Searchable database of every native function with parameters and examples.

  • FiveM Native Reference

    The same natives, documented for FiveM — often clearer write-ups, and your bridge to the paid FiveM world later.

  • GTA5-Mods.com

    Where mods are published and where players will find yours. Study what the top script mods do.

  • OpenIV

    The asset tool for vehicle, weapon, and texture work, with the safe mods-folder workflow.

  • LemonUI — GitHub

    The maintained menu library for C# mods. Successor to NativeUI.

  • GTAForums

    The old-school modding forum: showroom, tutorials, and help threads going back a decade.

Built for learning GTA V single-player modding with C# and ScriptHookVDotNet. Mod responsibly: back up your game, stay out of GTA Online with mods loaded, and credit the toolmakers — ScriptHookV and ScriptHookVDotNet are free community work that this entire scene stands on.

← Back to all guides