Precompiling your plugin - TiberiumFusion/TTPlugins GitHub Wiki

This article explains what precompiled plugins are and why you might want to precompile your plugin.

What does it mean to precompile a plugin?

A precompiled plugin is simply a plugin which has already been compiled into a .NET assembly before you place it in your Plugins folder. Normally, when you create and edit plugins in Terraria Tweaker 2, you are only working with your plugin's source code and do not have to compile anything yourself. When you launch a Tweak List that has source code plugins enabled on it, those source code plugins are automatically compiled into .NET assemblies. By precompiling a plugin, however, you have control over the output assembly and can achieve advanced techniques, such as embedded game assets in your plugin assembly.

There are some pros and cons which you must consider before precompiling a plugin.

Major Benefits

  • You can embed resources in the plugin assembly, then retrieve them in your plugin code. This can be used to create custom items, weapons, NPCs, etc by embedding custom sprites in your plugin assembly.
  • If you choose to precompile your plugin with an IDE, you will benefit from the productivity features of your IDE. For example, Visual Studio will provide you with IntelliSense and xml code docs that will reduce the likelihood of typos or coding mistakes.
  • Using a tool like ILMerge, you can merge external dependencies into your plugin's output assembly to ensure that those dependencies exist when your plugin is loaded into Terraria.

Major Drawbacks

  • Convenience. Terraria Tweaker 2's ability to compile your plugin on-demand provides a simpler workflow, which may suit simpler plugins. Getting all of Visual Studio up and running just to change one line of code can be obnoxious.
  • If the signature is extended for a method your plugin uses that lives inside Terraria, TTPlugins, or any other assembly your plugin references extended, you will need to recompile your plugin with updated references to target the newer assemblies. For example, if a Terraria update adds new parameter to Item.New() and your plugin uses that method, you must reference the updated Terraria assembly, potentially revise your code, and recompile your plugin. This is an unlikely possibility, but can happen.

Should I precompile my plugin?

This depends on your project and is up to you. However, consider the following:

  • Small plugins with few lines of code will be easier to manage & revise when kept in source code form.
  • Large plugins may require many different classes and dense logic, which will be easier to manage using an IDE.
  • Plugins that need embedded resources to add new assets to Terraria must be precompiled.

The scale of your project will most likely be the deciding factor.

How do I precompile my plugin?

If you want to precompile your plugin, you will need to setup yourself up with an IDE that can build .NET Framework assemblies. Create a project, reference TTPlugins.dll, and add your plugin source code files, then build your project. That's all there is to it.

If you would like to use Visual Studio, you can refer to the Developing with Visual Studio topics, which demonstrates this process in detail.