Why Use an IDE - tModLoader/tModLoader GitHub Wiki
This page will hopefully convince you to abandon making mods in Notepad. Be sure to click the links below to watch the videos. All info presented corresponds to Visual Studio, but other IDEs such as Rider and Visual Studio Code have similar functionality.
When you make a syntax error, you'll see red underlines under the bad code, similar to a spell check.
You can hover over the error to see an explanation.
Seeing the explanation above, we can fix the code easily by changing 20.5f
to just 20
.
Visual Studio can fix simple misspellings as well.
Simple.Misspellings.mp4
Sometimes Visual Studio can guess how to fix your error. For example, below we forget to add using Terraria.ID;
to our ModItem class.
Clicking Show potential fixes
or pressing the hotkey shows the following options.
Clicking the first option adds the appropriate using statement to our code. We can fix errors without trying to build in-game.
Show.Potential.Fixes.mp4
A common problem with new modders is that they don't know all the Terraria variable names or method names. For example, the various biomes/zones have names that aren't always what you might expect. You'll still need a little experience to know which class to look for these variables, but Intellisense helps immensely. In the video below, we see Intellisense suggesting the available Zones and downed bosses. Notice how Plantera being defeated is downedPlantBoss
. This is why Intellisense is so valuable to a self-sufficient modder.
Autocomplete.Field.Names.mp4
While you can waste your time looking up various vanilla IDs in our reference pages, it is much easier to just let Autocomplete do the work for us! Simply start typing your guess for the ID name and you will quickly see suggestions. You can select a suggestion to autocomplete it. How nice is that?
Method names are also suggested in the same way. In addition, you can see the method parameters, both their names and types. For example, I'd like to add a buff to an enemy when I hit him with my sword. Typing target.AddBuff(
will bring up the parameters, helping me complete my call to the AddBuff method.
Autocomplete.Method.Names.mp4
An extremely common task when making mods is to override various hooks such as SetDefaults or UpdateAccessory. Remembering the parameters to these hooks is sometimes hard to do. By using Visual Studio, you can easily write "override" followed by a space, followed by a few letters of the method you want to override, and then enter to easily override hooks. As a bonus, any missing using references will automatically be added to your code.
Before:
After:
Override.mp4
By using the extract mod feature, [Modname]_[Modversion].dll
(and optionally a [Modname]_[Modversion].xml
documentation file if it exists) will be placed in Terraria\ModLoader\references\mods
. This file can be added as a dll reference to your .csproj if your mod has a strong or weak reference to another mod (you'll still need the build.txt entries). This path is consistent and accessible from the Mod Sources folder, meaning that the reference added to .csproj is portable for all contributors for your mod, provided they extract the referenced mod on their computer. By doing this, you can enjoy auto-complete for the API provided by the mods you reference as well. Read more on that here.
With an IDE, such as VS, you can debug your mod. Debugging is the best way to pinpoint issues in your mod and solve them. While debugging, you can set 'breakpoints' which will make the application 'stop' and pause itself when it gets to that point. During this pause you can inspect what is happening, by for example looking at the values of variables in scope. You can quickly resume the application, or step over code to try to find the cause of a problem. To learn more about debugging, see its own guide.
With Edit And Continue (or eac) you can edit code after you've hit a breakpoint and see the effect of your edits in game immediately, rather than having to rebuild your mod manually. This is extremely useful for positioning projectile spawns or tweaking item defaults. Be sure to read edit and continue in order to use this feature. Note that things like ModItem.SetStaticDefaults
, ModTile.SetDefaults
, or other code might only run when the mod is loading, so they cannot benefit from eac.
In this video, we see 2 Example Gun spawned. After the first is spawned, a breakpoint is set in SetDefaults. Once it is hit, the game is paused and Visual Studio comes to the front. Then, item.damage
is changed from 40 to 80. We press continue and we can hover over the 2 items and see that the second item was spawned with 80 damage.
EAC.Change.Damage.mp4
In the Basic Projectile: Drawing and Collision guide, an example is shown using a breakpoint to test values for ModProjectile.SetDefaults
: Video
tModLoader will automatically provide documentation XMLdoc files, you can see documentation for a method when you hover it. For example, when the override
menu is active, clicking on an entry will show the documentation for that method where the purpose and potential usages of that method can be viewed:
Hovering over an existing overridden method will also show the documentation:
Hover over a method parameter to see details on what the parameter does:
Hover over fields or methods to see details:
Note that the amount and distribution of documentation is driven by modder feedback. If you find something that needs documentation, feel free to suggest it in the Discord chat.
Documenting your own mod can be useful, once the mod becomes complex. Try to document things that are important, but don't feel pressured to document everything, this is all for your own benefit. Writing readable code is better than documenting nonsensical code, after all. For more information on writing documentation, see XML documentation. The easiest way to document a method is to type ///
the line above a method, Visual Studio will autocomplete the template and you can type notes.
Modders making mods with API to be used by other mods can include [ModName].xml
files in their mod and they will be automatically extracted alongside their .dll
file and placed in tModLoader\references\mods
for easy collaboration (provided hideCode
is not true, which would be counter-productive for a mod expecting to be referenced by other mods.). XMLdoc files for mods can be generated in Visual Studio during a regular build and should be named [ModName].xml and placed in the root of the mod's source folder.
Find all references makes it easy to locate all usages of a variable in your whole project. Simply right click on a variable and click Find all references
. This is very useful to see where you assign and use your variables.
Find.All.References.mp4
By clicking on a variable or classname, you can press F12 (or Ctrl-Left Mouse Click) and Visual Studio will bring you right to where that class or variable is declared. If you do this on a class not in your code, such as the Terraria class Dust
or the XNA class Rectangle
, you will be led to a page with just the variables and methods, not the actual code. It is very useful to be able to read the Terraria code directly. Follow the "Go To Decompiled Code" section below to enable navigating directly into decompiled code, allowing you to view that code as well.
Go.To.Definition.mp4
By default, the Go To Definition
command will not allow you to see the tModLoader/Terraria source code. We can enable this feature to make modding much more productive. In Visual Studio, use the search (Ctrl-Q) to search for "decompile source". Click on "Enable navigation to decompiled sources" and then check the checkbox and click "OK":
From now on, you should be able to use the Go To Definition
command to view decompiled Terraria code. Try it now by typing Main.npc[0].CanBeChasedBy();
and use the Go To Definition
command on CanBeChasedBy
. After a delay as Visual Studio decompiles tModLoader, you should see the code of the NPC.CanBeChasedBy
method:
Imagine you name a variable or class something stupid and want to change it. Without an IDE, you would have to manually check each file the variable is used in and edit the text. Even something like "Find and Replace" would be error prone if you use similar names for other variables. Using the Rename function, you can easily rename classes and variables. Be aware that if you are using methods like mod.ItemType("Name")
rather than ModContent.ItemType<Name>()
, this won't work. This is also a great reason to use the <> type methods for ItemType and NPCType, it is much easier to maintain. In the video, we rename a variable called examplePet
to something better, airplanePet
.
Rename.mp4
Some Terraria methods have many many parameters. It can be hard to remember the order and types of those parameters. If you'd like to see the parameters of something like Item.NewItem or Projectile.NewProjectile, simply place your cursor inside the method and press Ctrl-Shift-Space
. You can navigate left and right and watch the bold parameter change. Press up and down to switch between overloads of the same method.
Parameter.Info.A.mp4
Parameter.Info.B.mp4
An extremely useful shortcut, Goto allows you to quickly navigate to and class, method, or field in your code. Simply type Ctrl-,
and the Go to All window will pop up. Type the name or part of the name and select the item to quickly navigate to the code. You can also type the first letter of each word in a name to find it. For example, typing eqf
will suggest ExampleQuestFish
. Visual Studio will smartly handle misspellings and partial matches as well. The video shows just how quick this feature can be and how easy it is to quickly navigate to other places in your code.
Goto.mp4
This context sensitive hotkey is useful in several situations. The suggestions depend on where the cursor is or what text is selected. Here are some useful actions:
If you are repeating yourself a lot in your code accessing the same object via fields and methods, sometimes your code can get a bit repetitive. Making a local variable and re-using that variable makes the code much cleaner. If you highlight the first occurrence of repeated object access, you can use this action to quickly introduce a local variable that you can then give an appropriate name to.
Introduce.Local.for.All.Occurrences.mp4
Properly formatted code is key for readability. Make sure to run this command before asking for help with your code as nothing is more annoying that poorly formatted code.
Format.Document.mp4
Sometimes, especially in Projectile and NPC AI, you might get lost within your code. This is especially true with nested if statements. Hover over the dotted lines to quickly see where you currently are in your code. For example, here I easily see at a glance where in the logic of my AI I currently am.
Folding code by pressing the -
or +
buttons can be useful if you need a wider perspective on your code.
Using this hotkey is useful when navigating vanilla code with large blocks of code within braces.
Goto.Brace.mp4
Launch profiles can be setup to streamline mod development and testing. For example, a profile can be setup to launch the game directly into the world, skipping the player and world select menus. Launching the debugger directly into the game saves time and clicks. Other uses of launch profiles include testing specific mod packs and maintaining a mod-specific save directory for organizational purposes. See Using Command Line Arguments for Debugging to learn how to use this feature.
Did you know that 3/2
in c# is 1
not 1.5
? Sometimes you might want to experiment with some c# syntax, but don't want to make a mod just to test the code. The c# interactive window is very useful for this. You can do whatever you want in the c# interactive, each command will execute it after you press enter. Alt-UpArrow
can be used to bring up previous statements.
C.Interactive.mp4
Git integration allows you to interact with your GitHub repository directly within your IDE. You can view diffs and make commits directly within your IDE. We recommend finding guides on Google to learn more.
This feature lets you invite someone into your project and collaboratively work on the code. Useful for mentoring other developers on your mod team or getting help on a tricky problem. Pair with Discord chat for voice chat.