Skip to main content

Choose your tools

After checking the loader chain, choose the editor you will use for Lab 0 and decide whether an AI assistant will be part of your workflow.

Your editor is your workshop bench​

Visual Studio Community is a practical starting point: completion helps you inspect the ScriptHookVDotNet API, compiler diagnostics catch mistakes while you type, and its debugger can attach to GTA5.exe when you need to inspect a running script.

VS Code, Rider and other editors can also work. Choose one that builds a .NET Framework class library and lets you inspect errors without fighting the toolchain.

Using an AI assistant​

There is no obligation to use AI here. You can complete the labs by hand and learn from the problems you solve yourself.

If you do want one, a coding agent works directly inside 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 functions as a tireless junior developer on your team, while you remain 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, provide a strict engineering contract.

From an idea to a design​

Lab 0 checks the installation without designing gameplay. In Stage 1, the game design document gives the mod a one-page plan before its first gameplay code is written.

The starter rules file: AGENTS.md​

Many coding agents can read project rules from AGENTS.md or a tool-specific file such as CLAUDE.md. Check how your chosen tool loads instructions; a file helps only when the tool actually reads it.

note

This rules file provides an adaptable starting baseline. It reflects essential engineering guardrails forged on production mods, to adapt to each project's constraints.

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. Autocomplete can miss a valid API; inspect the actual SDK, compile, and investigate warnings before using a name. Check 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): no class that does everything. One class has one responsibility, its own state, and an explicit lifecycle. Your main script only wires the systems together, it does not contain the 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:

  • "In a street encounter, a rival approaches the player and may start a fight. Before coding, identify who decides when the scene starts, who drives the rival's behavior, what ends the encounter, and what the player should see."
  • Agree on the responsibilities, the observable states and the conditions that end them. Then build and test those states one at a time.

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: GTA V runs fullscreen without an attached console terminal. The log file records the execution history of the mod. If a ped stands still in game without logging, there is no way to tell whether the ped failed to spawn, whether a state condition evaluated to false, or whether 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 silent, investigate what happened after that transition, including errors and the completion check.
  • 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 explore and build, then check what it changed. If you cannot explain why your mod changes state or when its actors are cleaned up, return to the code and the in-game result before moving on.

Choose your tools and keep control of the changes. Lab 0 tests the setup in the game.