查看中文版

TShock is a toolbox for Terraria servers and communities. That toolbox is jam packed with anti-cheat tools, server-side characters, groups, permissions, item bans, tons of commands, and limitless potential. It's one of a kind.

• Download: Stable or Experimental.
• Read the documentation to quickly get up to speed.
• Join Discord for quick questions and answers
• Join Telegram for in-depth support, conversation, and some swell Australian company.
• Download other plugins to supercharge your server.

• New to TShock?
• Experimental Downloads
• Developer's Guide
  • Background
  • Building
    • On Windows
      • The Terraria Server API
      • TShock
    • On macOS
    • On Linux
    • On Unix
      • The Terraria Server API
      • TShock
  • Working with Terraria
• Code of Conduct

These instructions assume Windows. If you're setting up on Linux or macOS, please refer to the in-depth guide (and don't forget to install the latest version of mono-complete on Linux).

1. Download the latest stable version and unzip the folder using your favorite unzip tool. Make sure that all of the files in the zip get into one folder. This is where your server will be stored. The file structure looks like this:

      GeoIP.dat
      Newtonsoft.Json.dll
      OTAPI.dll
      ServerPlugins\
      |------BCrypt.Net.dll
      |------HttpServer.dll
      |------Mono.Data.Sqlite.dll
      |------MySql.Data.dll
      |------TShockAPI.dll
      TerrariaServer.exe
      sqlite3.dll
   

2. Start TerrariaServer.exe and TShock will boot. Answer the startup questions, and you should be ready to roll. In the background, TShock made some folders for you. We'll come back to those later.

3. Startup Terraria. Connect to a multiplayer server via IP and enter localhost if you're doing this on your local computer. If you're doing it on another computer, you need its IP address.

4. Look at the server console for the setup code. Type /setup [code] (example: /setup 12345), then a space, then the code you see in the console in your game chat. Instead of chatting, you'll run a command on the server. This one makes you temporary admin. All commands are prefixed with / or ! (to make them silent).

5. Use the in-game command /user add [account name] [password] owner (example: /user add shank lovely-ashes owner) to create an account. This gives you owner rights on your server, which you can configure more to your liking later.

6. Login to your newly created account with /login [account name] [password] (example: /login shank lovely-ashes). You should see a login success message.

7. Turn off the setup system with /setup and your server is setup for initial use. TShock also created several files inside a new tshock folder. These files include config.json (our big configuration file), sscconfig.json (the server side characters configuration file), and tshock.sqlite. Don't lose your tshock.sqlite or you'll have to re-setup TShock.

8. You can now customize your configuration, build groups, ban items, and install more plugins.

To download experimental versions of TShock, you have two real options: AppVeyor builds or GitHub builds. You can also get archived Travis CI builds. Fair warning though: experimental versions of TShock are point-in-time releases that are not technically supported by us. If you have to report an issue, please make it clear which commit or branch you downloaded your build from, which service, and the build number if applicable.

On AppVeyor, click on history, find the build you want, click on the commit message, and then click on the artifacts tab. You can download either the debug or the release build. AppVeyor only keeps builds back 6 months though.

On GitHub, click on the actions tab, then click on "build server" on the commit or branch you want. If it was successful, you can download either the experimental release or debug artifacts.

For old builds from Travis CI, you can still get them (for now) from us directly, on our Travis CI artifact mirror. Please note that these builds should be considered legacy and for archival purposes only. If you need them in the long term, please raise an issue explaining why before they are removed.

Whether you want to contribute to TShock by sending a pull request, customize it to suit your own elvish desires, or want to build your own plugin, this is the best starting point. By the end of this, you'll be able to build TShock from source, start to finish. More than that, though, you'll know how to start on the path of becoming an expert TShock developer.

But first, you need some background.

Terraria is a C# application written on the .NET framework using the XNA game framework. TShock is a mod for Terraria's server, which is also written in C# on the .NET framework. Some might compare TShock to hMod in the Minecraft world (the precursor to Bukkit and its server, CraftBukkit). This is a good comparison to make in how the underlying build process works. When the project started, TShock was injected directly into the decompiled source code for Terraria. Unlike Minecraft, Terraria is not obfuscated, which means that many variable names and inner workings are sanely-named out of the box. Now, TShock uses advanced techniques to operate.

TShock is, first and foremost, a plugin written for the server variant of the Terraria API, an unofficial construct originally built by bladecoding. TShock has been colloquially used to refer to both the plugin as well as the server and plugin together. Similarly, the Terraria API's client version was abandoned long ago, and development of the Server API led to the abbreviation TSAPI, for Terraria Server API. The plugin TShock is executed by the Terraria Server API, which is in turn bound to the Open Terraria API, more commonly OTAPI. The Open Terraria API is maintained by DeathCradle.

Now, the way that TShock runs on TSAPI through OTAPI can be summarized as the following:

1. The Open Terraria API deeply integrates with Terraria by modifying the official server's binary directly. This is done through rewriting the Terraria bytecode, the CIL code, using a patching tool designed by DeathCradle and tools from the Mono project. For TSAPI, additional modifications are done to support TSAPI specific features. This done through the TShock Mintaka Patcher.
2. The Terraria Server API uses hooks provided by OTAPI to provide higher level hooks as well as legacy hooks for existing TSAPI applications.
3. TShock is executed by TSAPI, uses hooks provided by both TSAPI and OTAPI, and provides even higher level hooks and support tools to other TSAPI plugins.

With all of this in mind, the primary goal when compiling TShock is to remember that only the second and third layers are required to be interacted with. The first layer, OTAPI, is provided pre-compiled through NuGet. The second layer, TSAPI, is provided in the TShock repository through a git submodule. Its primary home is the Terraria Server API repository.

Let's get started.

1. git installed, you may gain help from this
2. dotnet core sdk 3.1 installed, you may gain help from this

Open your command line tool or terminal, input following commands

          $ git clone https://github.com/Pryaxis/TShock
          $ git submodule update --init

These commands will pull the source code down to your disk

If you are using IDE(like Visual Studio or JetBrains Rider ):

1. Open TShock.sln in the source code folder
2. Click the build button of your IDE

If you are using command line, just input dotnet build TShock.sln

Working with Terraria in TShock and in other Terraria Server API plugins is different from most other APIs. Due to the nature of how OTAPI works, you have direct access to all public fields in the Terraria namespace. This means that you can access Terraria member methods directly. TShock and other plugins do this quite often, mostly to modify the game world, send data, and receive data. Calls to Main are one such example of direct access to Terraria. This is the equivalent to net.minecraft.server (NMS) calls in CraftBukkit.

You might find yourself wondering where these fields are. Pryaxis provides the decompiled Sources to Terraria's server, updated with each release. Note that these decompiled servers do not re-compile. The process of fixing the decompiles has proven to be nearly impossible in a reasonable timeframe with the modern Terraria Server.

Finally, you may be interested in developing other Terraria Server API plugins. The TShockResources organization has several plugins you can look at and build on. TShock is itself a plugin, and most plugins are open source. This gives you ample room to figure out where to go next.

Need help? Join us on Telegram or Discord.

By participating in the TShock for Terraria community, all members will adhere to maintaining decorum with respect to all humans, in and out of the community. Members will not engage in discussion that inappropriately disparages or marginalizes any group of people or any individual. Members will not attempt to further or advance an agenda to the point of being overbearing or close minded (such as through spreading FUD). Members will not abuse services provided to them and will follow the guidance of community leaders on a situational basis about what abuse consists of. Members will adhere to United States and international law. If members notice a violation of this code of conduct, they will not engage but will instead contact the leadership team on either the forums or Discord.

Do not attempt to circumvent or bypass the code of conduct by using clever logic or reasoning (e.g., insulting Facepunch members, because they weren't directly mentioned here).

Thanks goes to these wonderful people (emoji key):

AviKav 🐛 ⚠️

Rodrigo Rente 💻 📆 ⚠️

Stargazing Koishi 💻 🚇

Axeel 📖 📆

This project follows the all-contributors specification. Contributions of any kind welcome!