1.0 ‐ Getting Started
Greetings, developers! This is the inaugural section of our comprehensive series on creating TShock Plugins. While it is strongly advised to have a foundational knowledge of C# and its syntax for this tutorial, we will strive to maintain a straightforward approach, providing explanations as we progress. If you are unfamiliar with C#, please consider enhancing your understanding by visiting W3Schools.
Setting Up Your Development Environment
Before we dive into the world of plugin development, you'll need to prepare your Integrated Development Environment (IDE) for .NET 6 development. In this guide, we'll be utilizing Visual Studio Community 2022, available for download here.
When installing Visual Studio, ensure that you select the following option:
For those who prefer alternative IDEs, consider the following options:
- JetBrains Rider (paid)
- Visual Studio Code (free)
- MonoDevelop (free)
Please bear in mind that our tutorial will focus on Visual Studio, and we won't be able to provide support for other IDEs.
Prepare to embark on your journey into the realm of TShock plugin development with the confidence that you are well-equipped for the challenges that lie ahead. 🌟📝🛠️
In the context of TShock plugin development, commencing your project requires a specific approach. With an appropriate IDE already in place, follow these steps to initiate your project:
- Project Creation: Start by creating a new project. Choose a Class Library as the project type. The objective is to compile your plugin into an assembly file (.DLL) to facilitate seamless integration with TShock. Click "Next," located in the lower-right corner.
- Project Naming: Assign a descriptive name to your project.
- Target Framework: Opt for .NET 6 as your target framework. This aligns with TShock's native version, ensuring compatibility. The use of other framework versions may lead to complications or incompatibility.
- Upon completing these configurations, click "Create" in the lower-right corner. Visual Studio will initialize the project setup process.
By adhering to these initial steps, you establish the foundation for your TShock plugin development endeavor in a methodical and professional manner. 🌟🔧👨💻
With your newly created project in view, your development environment should resemble the following:
While it's not obligatory, consider renaming your main class file for clarity. Right-click on Class1 and select Rename:
An input box will appear; here, you can assign a new name. For the purpose of this tutorial, we will name it TShockTutorialsPlugin. Now that we've updated the class file's name, let's proceed to install TShock's NuGet package. Navigate to your project in the Solution Explorer, right-click, and select Manage NuGet Packages.
On the Browse tab, search for TShock in the search bar and choose the relevant package:
Please ensure that you select the correct package, as several outdated TShock NuGet packages exist. Following this, click the Install button that appears on the right.
A few windows may appear; simply accept the terms for each one until the package installation is complete. This is the sole NuGet package required to initiate a TShock plugin. Once the installation is finalized, proceed to our main plugin class. 🛠️📦👨💻
At this juncture, our primary class remains unadorned:
namespace TShockTutorials
{
public class TShockTutorialsPlugin
{
}
}Compiling the plugin at this stage will reveal that TShock doesn't recognize it. To bridge this recognition gap, we need to imbue our main class with attributes that enable TShock, specifically TSAPI, to acknowledge our plugin.
Commence by inheriting the TerrariaPlugin base class into our primary class:
namespace TShockTutorials
{
public class TShockTutorialsPlugin : TerrariaPlugin
{
}
}If you're new to C#, you may observe that TerrariaPlugin is highlighted in red. This indicates that it is not yet recognized. To resolve this, we must inform the compiler of our intention to use TerrariaApi.Server, where the base class TerrariaPlugin is implemented.
If you're using Visual Studio, you can right-click on TerrariaPlugin, choose "Quick Actions & Refactoring," and then select the "using TerrariaApi.Server" option:
This action will insert a new line at the top of the file:
using TerrariaApi.Server;Alternatively, if you're not using Visual Studio, you can manually add this line at the top of the file.
Now, you will notice that TerrariaPlugin is no longer highlighted in red. However, our primary plugin class is:
Visual Studio informs us that we are not implementing the inherited members from our base class.
You have two options to address this issue. You can either use Visual Studio's "Quick Actions & Refactoring" to implement them automatically, or add them manually. In either case, your file should resemble the following:
using Terraria;
using TerrariaApi.Server;
namespace TShockTutorials
{
public class TShockTutorialsPlugin : TerrariaPlugin
{
public TShockTutorialsPlugin(Main game) : base(game)
{
}
public override void Initialize()
{
}
}
}Please take note that we also need to specify that we are using Terraria; in order to access the Main class.
Next, we must include an annotation above our class definition:
[ApiVersion(2,1)] // <---- Add this
public class TShockTutorialsPlugin : TerrariaPluginThis annotation informs TSAPI of the API version we are utilizing, with the latest version being 2.1. Note that we use a comma as a separator for the version number instead of a period. This is because we are providing two integer values, and this is how the version number is parsed. The annotation is essential for TSAPI to recognize this as a valid plugin.
You can then proceed to add the following overrides, providing various details about the plugin:
[ApiVersion(2,1)]
public class TShockTutorialsPlugin : TerrariaPlugin
{
public override string Author => "Average";
public override string Name => "TShock Tutorial Plugin";
public override string Description => "A sample plugin for educating aspiring TShock developers.";
public override Version Version => new(1,0);
public TShockTutorialsPlugin(Main game) : base(game)
{
}
public override void Initialize()
{
}
}These values are self-explanatory and will be displayed when the plugin loads in the console. Please note that the Version can contain up to four place values:
public override Version Version => new(1,0,1,2); // Represents 1.0.1.2And there you have it - your plugin is prepared. While it may not serve any specific function at this stage, compiling it will allow you to load it onto any TShock V5 server, where it will load successfully, and you'll observe an output in the console. 🛠️📦👨💻
This step is notably straightforward and takes only a minute, if not less. In Visual Studio, navigate to the top menu and select "Build," followed by "Build Solution." Permit the compilation process to run its course. Afterward, right-click on your project file in the Solution Explorer and choose "Open Folder in File Explorer."
Proceed through the following file paths: bin > Debug > net6.0. In this directory, you will locate your plugin assembly. For comprehensive error logging, it is advisable to copy all files into your TShock instance's ServerPlugins folder. Upon starting the server, you will observe an output confirming the presence of the plugin.
With these instructions, you possess all the knowledge necessary to configure your inaugural TShock plugin and have it recognized by TShock. While the plugin may lack functionality at this stage, the upcoming guides will provide insights into how to expand its capabilities. Happy plugin development! 🛠️📦🎉