Skip to content

tModLoader guide for players

Jump to bottom
Brian edited this page Aug 5, 2022 · 85 revisions

Clone this wiki locally

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

Steam Installation

To install tModLoader on Steam, you need to own Terraria on Steam. Simply browse for tModLoader on Steam and install it. The tModLoader installation will exist alongside the vanilla installation, allowing you to play both vanilla and modded without the hassle of reinstalling vanilla. Note that tModLoader does NOT currently support Family Share due to an issue with Valve's implementation. Active dialogs are still being had to fix it, we ask for your patience!

By Default, 1.4 tModLoader will be installed by Steam.

To access 1.3 (Legacy tModLoader)

Use either the manual install instructions below (look for Release version 0.11.8.9) or take the following steps:

Go to Library:

image

Find tModLoader:

image

Right Click tModLoader:

image

Click Properties to Open the Steam Game Control Panel

image

Select Betas

image

In the dropdown, select "Public-1.3-beta"

image

Close the Prompt (no code required)

image

How to uninstall?

Simply right-click tModLoader -> Manage -> Uninstall. Your vanilla install will be unharmed.

Steam Family Share Installation

For some reason, if you don't own Terraria and are instead using a family shared Terraria, tModLoader won't launch and will take you to the Steam store. We are looking into the issue, there is no known workaround for the 1.4 version.

On the 1.3 version, a workaround is to install tModLoader through steam as normal and then copy the steam_appid.txt file from the Terraria install folder to the tModLoader install folder, replacing the existing file. This does however break multiplayer.

Manual 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.

  1. Goto the releases page and download the tML release you want. (usually the latest for 1.4. For 1.3, the latest is v0.11.8.9)

  2. 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.

  3. [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

  4. [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.

  5. Done. You can now make a desktop shortcut for tModLoader and launch tModLoader from that.

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

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

Manual 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:

  1. Microsoft .NET Framework 4.5
  2. Microsoft XNA Framework Redistributable 4.0

How to uninstall?

  1. Open Steam, go to your game library section and locate Terraria.
  2. Let Steam verify the integrity of game files for Terraria, this will reconfigure your game files to run vanilla.
  3. Done. You can launch Terraria as usual.

If you use GOG, simply delete the tModLoader folder you made before. Your worlds and players will be saved.

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: https://giant.gfycat.com/ConsiderateClutteredBorer.mp4

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. image

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

This is the end of the page. Back to the top.