Setup your first project and write a basic plugin

From Torch Wiki
Revision as of 12:01, 17 December 2019 by LordTylus (talk | contribs) (Created page with "Creating plugins for torch is very easy. For most of the plugins you only need a few classes, and unlike the ModAPI for Keen Mods you are not limited by any kind of whitelist...")
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

Creating plugins for torch is very easy. For most of the plugins you only need a few classes, and unlike the ModAPI for Keen Mods you are not limited by any kind of whitelist that interferes with your code, or restricts access to runtime objects. Effectively you can do everything you want and change any behavior of the server.

The following sections give an simple overview of how to start development and creating some basic functionalities to your plugin. Of course this compilation is no step by step guide to create the plugin you wish to create, but offers the basic ideas of what you may/need to do.

Getting Started

First of all you need an IDE for developing because it will make your life a whole lot easier. Basically you can use any IDE you wish for c# .net development. This tutorial however uses | Microsoft Visual Studio as the IDE. The Community Edition is free to use, and after about a month only requires you to sign into a Microsoft account. Any Hotmail, Live etc. account will do. Chances are high you already have one.

Open Visual Studio and create a new Project. Depending on what kind of Plugin you wish to create you need to choose a different type of Project. Of course you can decide later, but knowing in advance has the advantage that Visual Stuido will add the needed references to standard libraries you need for creating and compiling the UI in advance so that you don't have to deal with that yourselves.

Creating a Plugin with UI (Choose if you are not sure yet)

If you are unsure if you want to create an UI for the User you can still choose this option. Even if you end up not creating an UI your plugin wont be hurt by it. So we Recommend using this.

For that you create c# WPF-App (.net Framework) and use .net Framework of version 4.6.0 or later for development (4.7.2 is recommended).

Vs create new project.png

However: This whole step is just needed to get the needed references into your project, as it is a bit tedious to do it yourselves. So after creating the project, change its type to ClassLibrary. Otherwise upon compiling it will complain about you not having a suitable main Method.

Creating a Plugin without UI

If you are absolutely sure you don't need an UI and are never planning to add one a simple ClassLibrary will do.

For that you create c# ClassLibrary (.net Framework) and use .net Framework of version 4.6.0 or later for development (4.7.2 is recommended).

Older versions may cause issues with any referenced DLLs that were compiled using a newer version of .net.

You don't have the required .net Framework?

Usually that should not be the case as you are most likely have developed before. But in case you usually program with a different language most of the time (for example java) you can download it manually | here

Managing Dependencies

Now you created an empty Project. For the sake of simplicity it is assumed you started with a WPF-App and therefore have a few default classes in your project. For now you can delete those as they are not needed.

To create plugins you have to implement against interfaces defined by torch. So there are a few References you need to import.

For Basic Plugin Development you need:

  • torch.dll
  • torch.API.dll
  • torch.Server.exe

You find these DLLs in your torch servers folder. Its recommended to use these and not to copy them anywhere, as they are automatically updated if a new torch version happens to come out.

For Logging its also recommended to include:

  • NLog.dll

into your project.

In the DedicatedServer64 Folder next to your torch.Server.exe you find the DLLs the game uses. You want to grab

  • Sandbox.*.dll
  • SpaceEngineers.*.dll
  • VRage.*.dll

However most of the VRage.*.dlls you will never use. It doesn't hurt adding them, but after you created a few plugins you have a pretty good feeling on which DLLs you need and which you don't. Just be adviced. VRage.Native.dll cannot be imported anyway so don't bother trying.

What have you done so far?

Now you should have archived the following goals:

  • Installed an IDE (if you hadn't already)
  • Installed the .net Framework (if you hadn't already)
  • Set up a new Project
  • Added the needed dependencies

So you are all set to create the first plugin.

Writing a Basic Plugin

Now that you have set up your project you can start by adding your Main class and Namespace.

Write the Plugins Code

Your Plugin needs to have a public class that implements TorchPluginBase and there must only be one class that implements that. When torch loads your plugin it checks every class its finds to look for the one that implements it. If there are none or multiple, you will get a log messages upon server start telling you it was unable to load your plugin.

Visual Studio creates new classes without visibility which causes Torch to not see your class and therefore not load it.

Here is a small example:

 1 using NLog;
 2 using Torch;
 3 using Torch.API;
 4 
 5 namespace TestPlugin {
 6 
 7     public class TestPlugin : TorchPluginBase {
 8 
 9         public static readonly Logger Log = LogManager.GetCurrentClassLogger();
10 
11         /// <inheritdoc />
12         public override void Init(ITorchBase torch) {
13             base.Init(torch);
14         }
15     }
16 }

The Init() Method is called by Torch's PluginManager to initialize it. In this Method you do everything you need to do to get your plugin up and running.

However: This Method will be called before the game is even started. So you cannot interact with anything else than Torch itself.

Also Worth noting: Unlike in-game scripts or mods you write for Space Engineers, all your code is compiled by yourself. So you are not limited in any functions. As long as it compiles, it will work.

Test your Plugin

To see if your Plugin works, lets just add a small Log Message to the Init Method and compile it.

1         public override void Init(ITorchBase torch) {
2             base.Init(torch);
3 
4             Log.Info("This is a Test if it works!");
5         }

After compiling you will find a bin folder in your projects directory. In that you find (depending of how you built it) a DLL file. This is your plugin.

Setup a Plugin zip

In order for Torch to load your Plugin you have to put the newly created .dll file into a zip-compressed folder. You can use Windows own way of doing that, or use a third party program like 7Zip or WinRar to do so.

Along with the .dll you have to add a manifest.xml which Looks like this:

1 <?xml version="1.0"?>
2 <PluginManifest xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
3   <Name>TestPlugin</Name>
4   <Guid>00000000-0000-0000-0000-0000000000</Guid>
5   <Repository>None</Repository>
6   <Version>v1.0.0</Version>
7 </PluginManifest>
  • Name
    • The Name is the name of your Plugin, it will be needed for Publication later on, cannot be changed once your Plugin is published and is also displayed in the Torch UI.
    • Assuming you have already settled on a good name just type it in there.
  • Guid
    • The Guid is a Unique plugin identifier, torch uses to tell plugins apart.
    • By that you can have multiple plugins with the same name. There are online generator that generate an GUID for you. As an example you can use: [1]
  • Repository
    • Repository is deprecated and can be left on "None". It was used to track plugin changes on GitHub, but since there is a website for that now it has no use.
  • Version
    • Version is used to distinguish between newer and older versions of your plugin. Versions should be formatted according to semantic versioning.
    • Torch uses the version number to decide whether to update a plugin to a newer version or not.

Now you should have a zip file that looks like this:

  • TestPlugin.zip
    • TestPlugin.dll
    • manifest.xml

There will also be a TestPlugin.pdb although it is completely optional you always should dump this file in your plugin zip also. The pdb file contains debug symbols that are loaded from torch as well. The main benefit is that you can actually see the line numbers in which exceptions happened. So if a user contacts your with a problem you are more likely to find its cause in the future.

So the recommended zip looks like:

  • TestPlugin.zip
    • TestPlugin.dll
    • TestPlugin.pdb
    • manifest.xml

Install your Plugin

You install your own plugin exactly the same as any other plugin. Just follow the instructions on [Plugins]

Dont Worry, you dont need to do that every time, once installed you just have to replace your .dll file in that zip. This should just be a drag and drop action after compiling. So its pretty easily done.

Start the Server

When starting you should find the following entries in your log:

18:27:14.7832 [INFO]   PluginManager: Checking for plugin updates...
18:27:14.9051 [INFO]   PluginManager: Updated 0 plugins.
18:27:14.9051 [INFO]   PluginManager: Loading plugins...
18:27:14.9241 [INFO]   PluginManager: Loading plugin at TestPlugin.TestPlugin
18:27:14.9241 [INFO]   PluginManager: Loading plugin 'TestPlugin' (v1.0.0)
18:27:14.9371 [INFO]   TestPlugin: This is a Test if it works!
18:27:14.9371 [INFO]   PluginManager: Loaded 1 plugins.

We see the PluginManager loaded 1 plugin, which is the one you just created. And we see our Log Message. It works!

Apply Changes to your Plugin

When applying changes to your plugin while developing you always have to restart your server. This can be a bit tedious as saving and loading takes some time.

It is recommended to use the | ALE Restart Watchdog plugin. You configure it to restart the server automatically after 1 second. So whenever you hit the stop button, type !stop in your console, or press the X on the UI this plugin will immediately restart your server. Saving precious time that would otherwise be wasted on unloading and saving the world.

If you need to save however you have to trigger it manually via !save command and wait for it to be completed.