Workshop
This Guide is only relevant for 1.4. The Mod Browser page is where you will find information relating to publishing mods for the 1.3 version of tModLoader.
The Workshop is an online component of tModLoader where Mod Makers can publish their mods. Users are able to easily find, download, and install mods they are interested through the workshop. Users can browse the workshop directly in-game by visiting Workshop->Download Mods on the main menu. Users can also visit the Workshop in their web browser or in Steam.
tModLoader will also load workshop items the user has subscribed to from the Terraria Workshop. Workshop items on the Terraria Workshop are not mods. Worlds and Resource Packs are the only types of content found on the Terraria workshop.
Modders wishing to publish their mod to the Mod Browser should continue reading.
Once your mod is working and functional, you may wish to share it with other users. You'll need a Steam Account and a working mod.
Modders wishing to publish their mod must have the Steam version of tModLoader. Additionally, the steam account must not be a limited user account. Usually, this just means that the account must have spent at least $5 on Steam.
// TODO: Can Family Share publish?
Modders must accept the Steam Subscriber Agreement. There is a link to this page on the publish mod menu as well.
In addition, the modder should read the rules. Mods violating rules will be removed:
- Terraria Player-Created Game Enhancements: Rules & Guidelines
- tModLoader Rules (TBD)
After making sure your mod is ready for release, visit Workshop->Develop Mods. You should see a Publish button, if you don't, build and reload your mod and it should appear. After pressing Publish, a menu will appear with some additional options. After selecting those options, click Publish and the mod will be published to the workshop. Before publishing, however, do the following:
Set a version in your build.txt. Something like 0.1 is good for an initial release. Please use semantic versioning: major.minor.patch You are not allowed to use letters for the version
This is the description that potential users will read when deciding if they will download, make it good.
This is what modders will see if they click the More Info button in-game. It doesn't support as many formatting options as description_workshop.txt, but it does support chat tags and colored text.
This is the description that potential users will read when deciding if they will download, make it good.
The contents of this file will populate the steam workshop page description for your mod. You can use bbcode markup code to add headings, links, and images. Modders can use the Edit title & description button on the workshop page of their mod to quickly edit and test formatting. If you do this, make sure to copy changes made directly on the workshop to description_workshop.txt so that the next time you publish an update to your mod the changes aren't reverted.
A lot. You don't want your mod to be quickly judged to be bad because of a poor first release.
Every mod can have a homepage in addition to their Steam Workshop page. This could be a thread on the Terraria Community Forums, a wiki, a GitHub, or even a Discord link (Not recommended). It is up to you. A homepage should provide a way to interact with your users so they can give bug reports, criticism, or praise.
Once you have a homepage, copy the URL and paste it into your build.txt on the homepage property. Save build.txt.
Save all your files and Build the mod in the Mod Sources menu.
If you have a Github repository for your Mod, push all changes.
On the publish menu, set tags for your mod that match the features of your mod. Set the visibility to public if your mod is ready for anyone to use it. Modders can use Private or Friends Only to facilitate beta testing prior to publishing.
You can now click the Publish button. Within a few minutes, your users will automatically have the updated mod.
To update a mod you have published, first do the following:
Increment the version in your build.txt. Your Version should be 2 to 4 numbers separated by periods. Do not add letters such as "v" or "beta" to your version. Read about versions. Note: Some examples: 0.1 is the same as 0.001, and 0.0.0.10 comes right after 0.0.0.9.
Update your description.txt and description_workshop.txt with any new info you'd like potential users to know about. A brief recent changelog might be nice here.
If a file named changelog.txt is found, it will be used to populate the Change Notes section of a mod's workshop page. Before publishing an update, clear out exiting text and type up the changes made since the last version published.
A Mod icon can be added to a mod by adding an 80x80 icon.png to the root of the Mod's source folder. This is the icon shown to the user in-game. In addition, the workshop website also supports a higher resolution icon_workshop.png. This file can be up to 512x512 pixels. If you want to keep the pixel art of the 80x80 icon consistent, you can upscale to 480x480 by scaling up by 600% and using the nearest neighbor upscaling option.
Here is a template if you wish to use it:
Test your changes a lot. Test the Save and Load code in your ModPlayer and ModSystem classes by loading old saves from previous versions of your mod.
Save all your files and Build the mod in the Workshop->Develop Mods menu.
If you have a Github repository for your Mod, push all changes now so your releases stay in line with the source code.
Click Publish in the Mod Sources Menu. Within a few minutes, your users will now see that an update to their favorite mod is now available for download.
If you have a website, now would be a good time to advertise the update and changelog.
Mods can publish different builds of their mods for stable and preview simultaneously. tModLoader will enable the appropriate version of the mod depending on the version of tModLoader the user is running, nothing needs to be done by the modder.
You can unpublish a mod by visiting the steam workshop page for your mod and selecting delete.
On the steam workshop page for your mod, use the Add/remove Contributors to add collaborators to your mod. The users must be your friend. This is mostly visual, collaborators have no control over the workshop page. To actually collaborate, modders usually use GitHub to work on code together.
If you find that your .tmod file is unnaturally big, check your Mod's source folder for large files that shouldn't be there. By default, all files in the folder will be packaged into the .tmod file. Use buildIgnore in build.txt to specify folders or files to ignore, or delete the files in question. Common culprits include photoshop or other image editing project files.
Modders can use Github Actions to build their mod with each commit. This can be useful to make sure the mod doesn't break.
Modders can also use GitHub actions to publish a mod update whenever build.txt is updated, but that is not something we have a working example of and is left up to the user. Modders using this approach will need to be EXTREMELY careful with their Steam credentials.
The displayName in build.txt dictates the name users will see when interacting with mods. This name can change and updated as the mod changes. Feel free to edit this as you like, your changes will take effect next time you publish. Read on if you need to change the internal name of a mod.
Aside from the displayName, there is an internal name. The internal name is another name pertaining to a mod, this name has no spaces or special characters and will not change as the mod is updated. For example, the Begone, Evil! (Disable Evil Biome Spread) mod's internal name is "DisableCorruptionSpread". tModLoader and other mods can interact with this mod within code using "DisableCorruptionSpread" and the connection won't be broken if the displayName changes.
The internal name must be unique on the workshop, so you might find that the internal name you have chosen for your mod is already taken when publishing. Or, you might want to rename the internal name for other reasons. Due to various factors, it is not recommend to change the internal name of a mod that has already been published, but it can be done. If your mod is small, it might be easier to make a new mod and copy over the changes rather than following the steps below to rename an existing mod.
Use the workshop search to find a new unique internal name. The search doesn't search by internal names, but it should give you an idea of what might be taken already. If you are on the tModLoader Discord, you can type the .mod ModNameHere command in the #botworld channel. Our bot will then reply with information about that mod if it exists or "Mod with that name doesn't exist" if a mod with that internal name has not been published. Repeat until you find a name suitable for your mod that is unused.
After deciding on a new internal name, first rename your mod's source folder. Open up the ModSources folder and rename the folder for your mod.
Next open up your mod's source folder and rename ModName.cs, ModName.csproj, and ModName.csproj.user if it exists. Open up ModName.cs and rename the Mod class. Open ModName.csproj in a text editor and rename the AssemblyName entry.
Next we'll need to update all the namespace entries on every .cs file in your mod. Open up each and rename each namespace ModName entry.
Make sure you saved all your changes on each file and try to build the mod in game. If the mod doesn't load or doesn't build, you likely missed something. The error message should help you find and fix the remaining issues.
Using the "Find in files" feature can streamline this process. In notepad++, for example, the "Find in files" tool can be used to search all files in a specific directory. From there each result can be fixed easily.
Mods published to the Mod Browser must abide by the TCF Modding rules Rules of note include the rule against porting content from non-PC versions of Terraria and the rules against plagiarism. Violating these will result in revoked Mod Browser privileges.
Any nudity or inappropriate content in a Mod Icon will result in especially severe response. What will be deemed inappropriate? You can probably guess it, but still here's a few examples: nudity/porno, swearing, violence/harm to other humans or animals, and also icons that encourage vandalism, crime, terrorism, racism, eating disorders, or suicide.. The list can go on.. just use an appropriate icon please.
Don't do it. The mods you upload are tagged with your Steam identity. You will be permanently banned from the browser and all of your mods will be removed. We will also notify Terraria and Steam staff about you and your malicious code.
// TODO: decription.txt too long error
Unconfirmed: If there is a Workshop folder in the saves directory, delete it. Try to publish again.