How to develop your first script mod for RDR2

This is part 1 in a series dedicated to creating your first plugin! You can already find the finished project and its source code at the bottom of this article, but this article so far only covers getting started.

With the arrival of RAGE Plugin Hook for Red Dead Redemption 2 creating modifications has become a whole lot easier. Leveraging the full power of the .NET ecosystem combined with an easy to use API for RDR2, it allows you to quickly create new mods without having to worry too much about all the scary stuff.

This tutorial is aimed at beginners, but ideally you already have some experience with programming to make things easier. If not, I am sure you will still understand most of the concepts, though it might take you a little longer. We will use C# as the language of choice and Visual Studio as our IDE. You can download a free copy of the "Community Edition" here: https://visualstudio.microsoft.com/vs/. When installing Visual Studio, make sure to at least select the ".NET desktop development" tools. Please note that this tutorial is aimed at beginners and does not necessarily reflect best practices for plugin development.

Setting up our development environment

Once you've installed Visual Studio, you can download my empty test project here: NPC Taxi Empty Start Project. It already contains a skeleton for a new RAGE Plugin Hook plugin called "NPC Taxi", which we will be developing in this tutorial. If you browse its folder structure, you will find a folder called "Dependencies" in it. This is where RPH's so called SDK is located.

This SDK allows us to make use of RAGE Plugin Hook and all its functions. It is regularly updated to include new functionality and all you need to do is update the file in there with the one included in the "SDK" folder when downloading a new version of RAGE Plugin Hook.

You should see this overview of your project's structure on the right when opening up the project. It shows you all files that are currently in the project, in this case two code files called "EntryPoint.cs" and "NPCTaxi.cs". Now I know I said the project was going to be empty, but it is empty in terms of not doing anything yet 😛

Entry point and exit point

Let's have a look at the two files. First, open up "EntryPoint.cs". At the top you can find metadata associated with your mod such as the name of the modification, its author, description and two more technical attributes: The entry point and the exit point. They are called whenever RPH loads and unloads your Plugin respectively and you can see them defined as OnEntry and OnUnloading if you check the code right below the metadata. We will not worry about unloading too much just now (who would dare to unload our amazing plugin anyways?), but focus on our entry point:

private static void OnEntry()
{
	NPCTaxi.Start();

	while (true)
	{
		NPCTaxi.Process();
		GameFiber.Yield();
	}
}

The first thing that happens is that we call a function in a different class, namely the function Start in a class called NPCTaxi. This function will be called once when our plugin is loaded and can be used to do one-time initialization such as loading a settings file. If you click somewhere on Start and press F12 Visual Studio will take you to the function. It will also open a new tab with the source file (NPCTaxi.cs) where this function is located in. As you can see, all it currently does it print a new help message and presents it to the user.

Let's go back to OnEntry again and see what happens next. We enter what is called a "while-loop". This means all instructions in the {} are executed as long as the condition for the loop is true. Since our condition is true, it is always true and the loop will run indefinitely. Hence, we have our main execution loop here. Every time the game processes its logic, we also get processed here until we are unloaded. There are two calls inside this loop, one to a function in NPCTaxi again (if you use F12 you can see that it does nothing) and a call to GameFiber.Yield. To keep things simple, what this call does is hand back control to the game after we have finished doing our shenanigans. If we do not do this, the game will freeze since the game still thinks we are doing stuff (and we run this loop indefinitely, remember?). When this function is called, the game resumes execution, processes its subsystems like physics and its other scripts and presents a new frame to the user. Once that is done, it hands control back to us and we return from GameFiber.Yield. We now run the loop again as our condition is still true.A more in-depth explanation can be found her: http://ragepluginhook.net/RPH2PreDoc/ under "Fibers".

Running our plugin

Now that we are experts on all things plugin development, let's compile and load our test plugin. Press Shift+F6 to build your current project (if that keybinding does nothing, open the "Build" menu at the top and choose "Build NPCTaxi"). This means that the code you have written is translated so that a computer can run it. This compiled code can then be found in the project folder under "bin\Debug" where you will have three files: "NPCTaxi.dll" (your compiled code), "NPCTaxi.pdb" (additional information for your code to help you when something goes wrong) and "RagePluginHook2.dll". The latter is the SDK we talked about earlier and is placed there for your convenience so you always know what files you would need to run your project. We do not need it in this case as it is included in the RAGE Plugin Hook download. Head over to https://www.mod-rdr.com/files/file/16-rage-plugin-hook/if you haven't already and download the latest version of RPH. Copy all its files into the game directory (for more details on the installation please refer to the file description).

Copy the two "NPCTaxi" files into a folder called "C#Plugins" in your game root directory, for instance: C:\Rockstar Games\Red Dead Redemption 2\C#Plugins. Now start the game with RPH and wait until you are fully loaded and can move your character. I strongly recommend to use windowed borderless (or just windowed) mode for development. By default RAGE Plugin Hook loads all plugins so chances are NPC Taxi is already running when you started the game. To reload it so we can see our help message, press F5 to bring up the console, type in ReloadPlugins and press Enter. If RPH did not load your plugin automatically, try typing in LoadPlugin "NPCTaxi.dll". Your plugin is now loaded and you can press F5 again to get back to the game. You should now see our help text in the left corner welcoming you to your new plugin. Amazing! 🙂

The finished project can be found here: NPC Taxi Source and part two of the tutorial is here