tModLoader guide for players - tModLoaders/tModLoader GitHub Wiki

I don't want to just play mods, I want to make them

I don't want to just play mods, I want to contribute to tModLoader

Installation

This installation is necessary for players who have purchased Terraria from GOG or who otherwise want to install a particular version of tModLoader.

Installing tModLoader is relatively easy.

Goto the releases page and download the tModLoader release you want.
1. Default/None/1.4.4: Visit latest and download tModLoader.zip
2. 1.3: Visit v0.11.8.9 and download the file corresponding to your operating system
3. 1.4.3: Visit the releases page and find the latest entry that mentions 1.4.3. Expand the section labeled "Assets" and click to download the "tModLoader.zip" file.
4. 1.4.4-preview: The download for the preview version of tModLoader for can be found by visiting the releases page. Find the most recent entry that has "preview" in the name. Expand the section labeled "Assets" and click to download the "tModLoader.zip" file. You'll need to regularly manually install new versions of 1.4.4-preview if you want to keep up to date with changes.
Unzip the contents of the zip you downloaded to a folder named tModLoader either next to or nested inside the Terraria install folder. On 1.4, if the folder contains a 'Build' folder, you will need to remove this intermediate folder and bring the contents up one level. (GOG usually installs to C:\GOG Games, and Steam to C:\Program Files (x86)\Steam\steamapps\common\Terraria. See this video to find the steam installation location if you customized it.) (If you are on linux and own the game on GOG, the nested option inside Terraria\game is preferred) If you don't know how to unzip a zip file, get someone who knows how to use a computer to help you.
- Option 1, side-by-side (Recommended):
- Option 2, nested:
- DO NOT install the tModLoader files directly into the Terraria folder. This option not supported for GOG on Mac.
[This step applies to 1.3 ONLY] Remove or Add the Steam files depending on which version of the game you own:
1. If you are using the GOG version of Terraria, delete the Steam file from the folder you just extracted tModLoader into (these files might already be deleted from the zip you downloaded):
  - Windows: steam_api.dll
  - Linux: lib/libsteam_api.so and lib64/libsteam_api.so
  - Mac: tModLoader.app/Contents/MacOS/osx/libsteam_api.dylib
2. If you are using the Steam version of Terraria, if the Steam files are missing from the zip, copy them from your Terraria install to the tModLoader install:
  - Copy the steam_appid.txt, then, depending on your platform:
    - Windows: steam_api.dll and CSteamworks.dll
    - Linux: lib/libsteam_api.so, lib/libCSteamworks.so, lib64/libsteam_api.so, and lib64/libCSteamworks.so
    - Mac: tModLoader.app/Contents/MacOS/osx/libsteam_api.dylib and tModLoader.app/Contents/MacOS/osx/CSteamworks
[1.4 ONLY] GoG users will need to install Steam if they haven't already. Our Mod Browser uses some of the steam install files to facilitate accessing the Steam Workshop. You should NOT need an account/be logged in for this to work.
Special Note for Linux: If your steam installation is not recognized (Error "unable to access steam workshop"), try uninstalling it and reinstalling Steam from the APT repositories via the terminal
Done. You can now make a desktop shortcut for tModLoader and launch tModLoader from that. (The file start-tModLoader.bat launches the game, that is what you could make a shortcut to.)

Tip: Here is an easy way to find where your Terraria files are located: (video example)

Locate Terraria in your Steam game library, right click it and click 'Properties'
Browse to the 'Local Files' tab and click on the 'Browse local files...' button
You are now in your Terraria folder (this is where you should install tModLoader)

Installation Common Issues

Windows 1.3 only: If the game doesn't launch at all, you might not have .NET 4.5 or XNA 4.0 installed. Download and run both installers:

Downgrade tModLoader

1.4 tModLoader updates every month. Sometimes a mod you are using fails to update in a timely manner and will cease to work with the latest tModLoader 1.4 release. You can manually downgrade if this is the case. To manually downgrade, find the latest release for the version you used to use on releases page and download it. It is a tModLoader.zip file. For example, if you launch tModLoader and it recently updated to v2022.06+ and it stopped working with an important mod, you can find the latest v2022.05+ release and download it. After downloading, open up the tModLoader install directory and delete all the files. Make sure you are in the install folder and not the saves folder. To find the install directory, right click on tModLoader, click Manage, then Browse Local Files. This video shows that process. After deleting the original files, you can take the files from the .zip you downloaded and put them in the install folder. This video shows this process. Once you know the outdated mod updated, you can delete all files in the install directory and use steam to verify game integrity to upgrade back to the current tModLoader release.

To use 1.3, simply select 1.3-legacy in the tModLoader betas menu: video

Dual Install - Have 1.3 and 1.4 tModLoader installed at the same time

You can keep 1.3 and 1.4 tModLoader installed at the same time if you utilize Steams ability to add non-Steam games. To do this, first switch to 1.3-legacy and make sure the download finished. Open the install folder and copy all the files. Go up one level and make a tModLoader13 folder. Go into the tModLoader13 folder and paste the files. In Steam, switch back to the default beta branch on tModLoader. Next, click on the Games menu and click Add a Non-Steam Game to My Library. Click Browse... and navigate to the tModLoader13 folder, most likely this will be "C:\Program Files (x86)\Steam\steamapps\common\tModLoader13". Click on "tModLoader.exe", click "Open", then click "Add Selected Programs". Finally, right click on the 2nd tModLoader entry in your library and click properties, then change "tModLoader" to "tModLoader 1.3" and close the window. Now you have the legacy tModLoader and the auto-updating 1.4 tModLoader both in your library.

Migrate Everything From 1.3 to 1.4

For the most part, the transition from 1.3 to 1.4 should be a clean start. The 2 are practically different games, and available mods won't match up. If you want to, however, you can migrate existing mods, worlds, and players.

Mods

Be aware the most of the mods you used on 1.3 might not be on 1.4. You can manually search for mods in the "Download Mods" menu, or you can use a modpack file to attempt to download all of them in one go. First, open up the 1.3 saves folder and find the enabled.json file in the Mods folder, this might be in \Documents\My Games\Terraria\ModLoader\Mods\enabled.json. Open up 1.4 tModLoader, click Workshop, Mod Packs, and then click Open Mod Pack Folder. Paste the enabled.json file that you copied earlier into this folder. Click Back and then Mod Packs to refresh the menu. You should see an entry for "enabled". Click View Mods in Mod Browser then click Download All. You'll most likely get a message that not all mods were found on the mod browser. If you do, simply click the download button on each mod in the listing.

Players

Use the in-game menu to migrate players. Cloud players will not show up so you will have to switch to 1.3-legacy and take them off the cloud if you wish to copy them over.

Worlds

Use the in-game menu to migrate worlds. Cloud worlds will not show up so you will have to switch to 1.3-legacy and take them off the cloud if you wish to copy them over.

My worlds and characters disappeared when I installed!

tModLoader DOES NOT use your vanilla world and player files. The in-game should give you the option to copy over your original vanilla files. This option won't work for players and worlds you have used in Terraria 1.4. You do not have to worry about your vanilla saves being modified; they will be copied for modded gameplay use. When you go back to vanilla, you will see your original saves.

tModLoader uses separate folders to store player (.plr) and world (.wld) files, mainly because it will store additional data for them. Your vanilla players and worlds will be stored in: %UserProfile%\Documents\My Games\Terraria (for Windows) in the Players and Worlds folders respectively.

If the automatic copy doesn't work, copy the "World" and "Player" folders from %UserProfile%\Documents\My Games\Terraria to %UserProfile%\Documents\My Games\Terraria\tModLoader.

How do I download and play mods?

tModLoader comes with a mod browser. Refer to the mod browser guide to learn how to download and play mods.

I have too little memory to run multiple mods!

Terraria and 1.3 tModLoader are 32-bit applications. In short, this means they are only capable of utilizing up to ~4 GiB of RAM. With a lot of mods, you may run out of memory. The solution is using less mods, unfortunately. Alternatively, you can try using the unofficial 64-bit version of 1.3 tModLoader.

1.4 tModLoader is 64 bit by default, which alleviates this problem.

I use macOS Catalina. What do I do?

If you experience any problems, try using the 64-bit version of tModLoader or talk to us on Discord.

How Do I Use Mod Packs in 1.4?

1.4 tModLoader significantly overhauls the Mod Pack feature to provide several additional functionalities.

To start with, save your Enabled Mods as usual. The UI will now show a lot of buttons. Let's walkthrough them.

First and foremost, I will use two different terms moving forward: A mod pack will refer to a frozen copy of mods that don't update with time. A mod collection will refer to a list of mods that are always the latest.

The first 2 buttons operate on the 'Mod Collection' style. Enable Only this List - disables all mods, and than loads only those defined in the collection Enable this List - loads mods defined in the collection on top of any existing loaded mods. Useful for stacking collections

View List & View Mods in Mod Browser allow you to see what the mods in the pack/collection are, and download them freshly on the mod browser for yourself.

Update List with Enabled - Updates the mod pack or collection with the currently enabled set of mods. Will delete or add to the collection/pack as required

Import Pack (Local) - Tells tModLoader to check the mod pack for the frozen set of mods to load. Any mods loaded from the Pack, while active, will override any existing mods you have downloaded. When a Mod Pack is active, it will shows as such in the Top Right Corner.

Remove Pack (Local) - Undoes the changes made by Import Pack (Local)

Export Pack Instance - Exports a copy of the ModConfigs and /Mods folder to InstallDirectory/ so that you can either setup a second instance of tModLoader with an older version OR quickly setup a server with the pack. Check InstallDirectory//SaveData/Mods for an install.txt file listing all the workshop publish ids and a tmlversion.txt labelling the tml version to use.

Delete Instance - Deletes the exported instance files created by Export Pack Instance