Skip to main content

Choose your tools

The workshop is real: the loader chain works, and Visual Studio builds C# against the right framework. Before P0, one last setup decision. It is not about hardware. It is about the two tools you will spend every session with: your editor, and whether you bring an AI assistant along.

Your editor is your workshop bench​

You already installed Visual Studio, and for this course that is the right choice. Not because it is fashionable, but because it gives you three things a text editor cannot. IntelliSense completes the API as you type, which is how you discover ScriptHookVDotNet instead of memorizing it. Live compiler diagnostics surface mistakes the moment you type them. And the debugger attaches to the running GTA5.exe so you can see exactly which line froze the game.

Other editors exist, and some are lovely. But a first project is not the time to fight your tooling. Learn the craft on the bench that has the debugger built in, then decide later whether you want to move.

The AI assistant: your choice, not a requirement​

There is no obligation to use AI here. Every project in this course is designed so you can build it by hand, and a lot of the learning happens exactly when you are stuck. If you enjoy figuring things out alone, nothing in this school requires an assistant.

If you do want one, the modern way is not a chatbot you paste code into. It is a coding agent that lives in your project: opencode, Google Antigravity, Claude Code, Codex, and others. You describe a problem in your editor, and the agent reads your actual files, proposes changes, and you decide what to keep. They differ in interface and in which model powers them, but that detail matters less than the habit you form around them.

How I actually work with an agent​

Here is the workflow I landed on after hundreds of hours building mods like Street Riders and InteractV. An AI coding agent is not a polite academic tutor asking you Socratic questions. It is a tireless junior engineer on your team, and you are the lead engineer.

In GTA V modding, letting an agent code without guardrails leads straight into a wall:

  • It hallucinates native functions and ScriptHookVDotNet methods that never existed or were deprecated years ago.
  • When a ped freezes in an animation, it wraps the code in an arbitrary timeout instead of diagnosing the broken state transition.
  • When a script crashes, it guesses in circles and rewrites working code instead of inspecting the game logs.

To get reliable work out of an agent, you do not ask it to pretend to be a teacher. You give it a strict engineering contract.

Conception first: the craft of the modder​

Before writing a prompt or touching a line of C#, the most critical step happens in your head: you have to know what you want and be able to describe it clearly in plain language.

Never just tell an agent: "I want street drug deals in the game." A vague prompt produces a shallow, robotic script that breaks after two minutes.

You have to think through the entire scene chronologically from the player's eyes:

  • What happens first? Does the buyer walk up casually, make eye contact, or signal the player?
  • What are the conditions? Does the deal require daylight, a dark alley, or a specific gang territory?
  • What if the unexpected happens? What if a police cruiser turns the corner mid-transaction? Does the buyer run, toss the package, or pull a gun?
  • How does the player experience it? Do they read spoken lines in a subtitle, or does an immersion-breaking menu pop up? What feedback tells the player the deal went through?

Behind every plain-English intention lies an engine reality that an agent will never invent for you:

  • "He holds eye contact": What native actually controls this? It is TASK_LOOK_AT_ENTITY (ped.Task.LookAt(target)), not a made-up helper.
  • "In an alleyway": GTA's RAGE engine has no magical concept of an 'alley'. How do you detect one? Do you cast two horizontal raycasts (World.Raycast) to check for tight walls within 4 meters, and ensure you are far from a major vehicle node (GET_CLOSEST_VEHICLE_NODE)?
  • "In gang territory": How do you prove it? Do you query the map zone (GET_NAME_OF_ZONE), scan nearby ambient peds for their gang affiliation, or check a polygon in a data-driven territory config file?
  • "Making a subtle gesture": Which animation dictionary does the game actually use? Which 3D prop does the ped hold in their hand?

If you let an AI guess these details without grounding them, it will invent fantasy functions like World.IsPlayerInAlley(), hallucinate animation names (anim@drug_deal@nod), or use non-existent prop hashes that silently fail in game.

Conception means bridging your creative vision to real game mechanics and assets using trusted databases (detailed in our Useful links guide):

You can brainstorm this phase with the agent: ask it to interrogate your idea, challenge your assumptions, or propose edge cases you had not considered. But an AI has no personal taste, no sense of rhythm, and no memory of what made you fall in love with GTA. Bringing a cohesive, living world to life that players genuinely enjoy requires human intent and judgment. That vision is your real job as a modder.

The starter rules file: AGENTS.md​

Modern coding agents like Claude Code, OpenCode, Google Antigravity, and Cursor read project rules from a file at the root of your workspace: AGENTS.md (or CLAUDE.md). When the file is present, the agent loads these constraints into its context at the start of every session.

note

This rules file is a generic starting point, not an absolute dogma set in stone. It reflects the essential engineering guardrails forged on production mods, but you should adapt its rules, paths, and constraints to fit your own project.

Create an AGENTS.md file in the folder where your mod solution lives:

# AGENTS.md

Starter rules for GTA V C# modding with ScriptHookVDotNet.

## Core rules

1. NEVER GUESS: Even with high confidence, always ask clarifying questions before writing code. Clarify triggers, expected ped behavior, and edge cases before proposing changes.
2. VERIFY AGAINST REAL SOURCES AND THE SDK: Never invent a native, an animation dictionary, or a prop hash from memory. If a method does not autocomplete in the SDK or causes a compiler warning, it does not exist. Always check against trusted databases before writing:
   - Natives: CitizenFX index (https://github.com/citizenfx/natives or https://docs.fivem.net/natives/)
   - Animations: Pleb Masters Forge (https://forge.plebmasters.de/animations) for real animDict and animName
   - Props and Objects: Pleb Masters Forge (https://forge.plebmasters.de/objects) for valid object hashes and models
   - C# SDK: real ScriptHookVDotNet3.dll assembly and decompiled reference scripts
3. DIAGNOSTIC LOGS FROM DAY ONE: Instrument your code with logs while writing it, never after you are already stuck:
   - Log the four critical checkpoints: Decisions (why an action was chosen), Transitions (from State A to State B), Fallbacks (target lost, path blocked), and Results (task completed, entity cleaned up).
   - Always include context: Timestamp (`Game.GameTime`), entity handle, state name, and distance. Never write empty logs like "running" or "ok".
   - Zero per-frame logging: Never write to disk on every `OnTick` frame. Log on events, state entries, and state exits to avoid killing performance.
   - When a bug occurs, read the logs before guessing: if a bug is not visible in the logs, add probes to the execution path before modifying any logic.
4. SRP AND DATA-DRIVEN ARCHITECTURE BEFORE CODE: Always define responsibilities and data contracts before writing implementation lines:
   - Single Responsibility Principle (SRP): Zero God classes. One class has one responsibility, its own state, and an explicit lifecycle. Your main script is a composition root, not a dumping ground for game logic.
   - Data-driven by design: Zero hardcoded tuning in C#. Externalize feature toggles (enable/disable), distances, multipliers, and cooldowns into configuration files (.ini or XML) so features can be switched and tuned without recompilation.
   - Explicit FSM: Model ped and mission behaviors as state machines with clear transitions, never nested if/else mazes.
5. CLEAN ENTITIES AND ZERO CHEAT TIMERS: Every spawned ped, vehicle, or blip must be cleaned up on reload or script abort. Never wrap a stuck state in an arbitrary timer to force completion: fix the actual completion condition.

The three-phase workflow​

Once your rules file is in place, structure every session into three distinct phases instead of asking for a whole script in one prompt:

1. Scoping, SRP, configuration​

Before generating a single line of C#, force the agent to define the architecture:

  • "I want a bodyguard that follows me and defends me against attackers. Before writing any code, list the classes and their single responsibility (who decides vs who executes), the FSM states this ped needs, and what tuning parameters belong in a .ini file so I can toggle features and tune distances without recompiling."
  • Agree on the states (Following, Combat, Returning), the SRP split (a controller that scans and a state that drives the ped), and the config keys (Enabled=true, FollowDistance=5.0). Correcting a bulleted architecture takes ten seconds. Refactoring a two-hundred-line tangled script takes hours.

2. Implementation, diagnostic probes​

Have the agent write code in small, focused contracts, and instrument it immediately:

  • The C# compiler and IntelliSense are your first line of defense: zero errors and zero warnings against the real SDK.
  • Place diagnostic logs while coding, not after it breaks: GTA V runs fullscreen, and you cannot watch a live console while playing. Your log file is your flight recorder. If a ped stands still in game without logs, you are completely blind. You cannot tell whether the ped failed to spawn, whether a state condition evaluated to false, or whether GTA's ambient AI canceled the task.
  • Ensure every state change logs its four critical waypoints: the decision to act, the transition itself, any fallback if an actor disappears, and the final cleanup.
  • Add simple visual debug: a temporary subtitle or on-screen debug text showing the ped's current state and target handle gives you instant confirmation in game without alt-tabbing.

3. In-game diagnosis on real facts​

When you test in game and something breaks (a ped stares into space, a vehicle drives into a wall), never ask the agent to guess why:

  • Open ScriptHookVDotNet.log or your custom mod log file.
  • If the log says Transition: Idle -> Approach [Ped 104] and then goes completely silent, you already know the bug is inside the completion check of Approach.
  • If the bug is invisible in the log, your probes are misplaced: add logs to the decision branches first, reload with Insert, and diagnose on measured facts instead of guessing in circles.

The line you should not cross​

Use AI to build and understand faster, never to skip understanding. If you finish a project and cannot explain how its state machine transitions or why an entity is disposed, you did not learn it, you rented it. The projects in this course are checkpoints precisely because the game does not care about good intentions: either you understand your bodyguard, or it shoots you.

Choose your bench, set your rules, and keep your hands on the wheel. P0 is where your setup gets tested for real.