• I don't want to contribute to tModLoader, I want to play mods
• I don't want to contribute to tModLoader, I want to create mods

If you still need to install tModLoader refer to the tModLoader guide for players.

You will need an IDE (Integrated Development Environment) to help develop tModLoader.

• For Windows users, we recommend Visual Studio 2022 Community Edition.
• A prevalent cross-platform alternative would be Jetbrains' Rider, but unlike VS2022 it is not free (unless you acquire a FOSS Contributor or Student license).

If you've never used Git before, checkout our guide on how to use it. If you ever come across something in this guide you don't recognize, just Google it. You should be easily able to find something relevant to your problem. You can also checkout this little snippet. Further, if command line inherently scares you, additional tools such as GitHub desktop and Github Extension for VisualStudio can provide most of the functionality you need in a user friendly interface.

tModLoader uses its own code patcher tool, which you will have to use if you want to contribute to tModLoader. We are required to use a patches system because we are not allowed to upload vanilla source code publicly. It also allows for relatively easy code maintenance.

Note: The setup GUI (Graphical User Interface) is currently Windows-only, use CLI (Command-Line Interface) on other systems!

1. Install .NET 8.0 SDK;;
2. Fork this repository, then clone your fork onto your PC. You HAVE to use Git for this, downloading source code as a zip file won't work;
3. GUI: Open setup.bat in the root folder;
   CLI: Open a terminal in the root folder;
4. GUI: Click on 'Setup' (top left button);
   CLI: Run ./setup-cli setup;
   • If asked, select your vanilla Steam Windows 1.4.4.9 Terraria.exe.
   • If you want to work on the 1.4.3 or 1.3 version of tModLoader, you need Terraria_1.4.3.6.exe and TerrariaServer_1.4.3.6.exe, or Terraria_1.3.5.3.exe and TerrariaServer_1.3.5.3.exe.
5. When decompilation is complete, verify that you have these folders:
   • src/decompiled/
   • src/Terraria/
   • src/TerrariaNetCore/
   • src/tModLoader/ (You will be primarily modifying files within this folder, through the patcher and tModLoader.sln file)
6. To open up the tModLoader workspace, navigate to solutions/ and open tModLoader.sln with your IDE.

Start:

1. Pull the 1.4.4 branch. You HAVE to use Git for this, downloading source code as a zip file won't work;
2. Create a new Git branch for the feature you're developing (i.e. feature/something_new or fix/that_thing);
3. Run Setup (setup) or Regenerate Source (regen-source) in the development GUI/CLI;

Develop:

1. Develop your contribution using solutions/tModLoader.sln and your IDE;
   • Please follow the established tModLoader Style Guide when making changes.
2. Diff <workspace> (diff <workspace>) the workspace you developed it for to turn your code into patches;
   • Your workspace is tModLoader 99% of the time. If it isn't, we imply you know what you're doing.
3. Create a new commit to commit the patches/ folder
   • Before you push your commit, please check our contribution article. Thanks!
4. If the branch was modified by someone else - pull the patches in Git and Regen Source(regen-source) in setup to apply them to your code.
5. Repeat.

Open the pull request:

• When you're done, PR your branch to 1.4.4, and not to master, preview, or stable.
• If you're in need of early feedback - you can and should open pull requests before they're done! They can be marked as drafts if needed.

If you are testing bug fixes, simply debugging the Debug configuration is all that is required.

As you add features to tModLoader, you'll want to add examples of using those features to Example Mod. Example Mod, however, needs to be located in the ModSources folder to build and test the mod. While you could copy and paste the folder back and forth between your ModSources folder and this repository folder whenever you wish to push your changes, a better approach can be achieved by using a symbolic link. A symbolic link allows a single folder to exist in 2 places at once. By creating a symbolic link in ModSources pointing to the ExampleMod folder in this repository, you can easily keep ExampleMod up to date and push changes to Github. Here is the command for creating the symbolic link on Windows.

1. Open the Command Prompt as Administrator by right clicking on it in the start menu and selecting "Run as Administrator"
2. Find the path to both your ModSources folder and the ExampleMod folder within your local copy of this repo.
3. Make sure the ModSources folder doesn't already have an old ExampleMod folder, delete it if it exists.
4. Run the command using your folder paths: (Below is just an example)

mklink /D "C:\Documents\My Games\Terraria\tModLoader\ModSources\ExampleMod" "C:\Users\MyNameHere\Source\Repos\tModLoader\ExampleMod"

5. You should see a message "symbolic link created for ..." in the command prompt. In ModSources, you'll see that the ExampleMod folder now has a little icon similar to desktop shortcuts. Now, you can edit ExampleMod and the changes will reflect wherever you cloned this repo to.
6. To properly open ExampleMod.csproj, you need to navigate to C:\Documents\My Games\Terraria\tModLoader\ModSources\ExampleMod and open the ExampleMod.csproj file from File Explorer. Opening it from within Visual Studio with File->Open->Project/Solution... won't work, it will have the wrong working directory. Build ExampleMod once it is open to make sure there are no problems before starting.

Before you're about to make a contribution, please check this article. Thanks in advance.

NOTE: it is wise that you backup your edits before pulling latest patches, if you have any that you haven't committed yet. Applying the latest patches will delete any of your work not included in them.

Setup (do this if you're updating your code for the first time, it also requires that you have some kind of command line git client installed)

1. Open a Git Bash window or whatever in the tML folder
2. Enter git remote add upstream https://github.com/tModLoader/tModLoader/
3. To ensure that it's been setup correctly, enter git remote -v and you should see something like this:

origin  https://github.com/*YOURUSERNAME*/tModLoader.git (fetch)
origin  https://github.com/*YOURUSERNAME*/tModLoader.git (push)
upstream        https://github.com/tModLoader/tModLoader (fetch)
upstream        https://github.com/tModLoader/tModLoader (push)

Actually pulling

1. Open up another shell window (if you want, enter git remote -v to make sure everything's as it should be)
2. Enter git fetch upstream
3. Then git merge upstream/*branchtomerge*
   • This will pull all the newest commits from branchtomerge into the branch that you have checked out
   • You should verify that you now have the latest patches, located in patches/
4. Open setup.bat in the root folder
5. Click on 'Regenerate Source' (bottom right corner)
   • After this process you can open solutions/tModLoader.sln as usual with the updated code

Simply stash changes and checkout.

1. Open in git shell/bash or whatever
2. Run git stash save or git stash (should default to save)
3. Run git checkout -b xxxx
   • Replace xxxx by branch name
   • Omit -b if not creating a new branch
4. Run git stash pop

TModLoader development no longer requires downloading specific Terraria versions, but if you need them for reference, then follow these steps:

• Download the DepotDownloader utility.
• Head over to this SteamDB page, pick and remember the depot (OS) you want, navigate to Manifests, select the public branch in filters, and grab the manifest ID of the version you need.
• Run ./DepotDownloader -app 105600 -depot <depot ID> -manifest <manifest ID> -username <steam login> to download that version.

If you would like to contact us or tModLoader users, it's best to join our Discord server. Discord is a chat and voice application.