Providing LUA packages

On this page we will explain how you can provide a LUA package to the Onset server by your Onsharp plugin as source.

What is a LUA package?

A LUA package is a package containing server scripts, client scripts as well as other files. This packages are getting loaded by the Onset server by default. Onsharp uses another mechanic: Instead of packages it uses a plugin loader which only can handle one DLL, but it does not need more than that. For more information about the topic "LUA packages" we recommend to go to the Onset wiki here. But Onsharp has the big problem, that it is only server side and when you want to do game related stuff like HUD or changing the environment, you need client scripts which gets loaded into the game by Onset itself and there is your only option: a LUA package. But to make the process as simple as possible we implemented package providers with Onsharp v1.0.11. Read on to learn more.

What are Package Providers?

The package provider is a helper class which generates a Onset LUA package from the given sources which are given to the package provider. After the export process, Onsharp will register the package and inject it into the server runtime of Onset, so that it is getting loaded.

How do I implement these Providers?

As always in Onsharp we try to make it as simple as possible, and we tried our best to implement these technique as simple as possible, too. First of all you need to create a package providing class and extend the existing Onsharp.Native.PackageProvider class.

using Onsharp.Native;

namespace Tutorial
{
    public class MyPackageProvider : PackageProvider
    {
        
    }
}

In order that the provider can be instaniated you need to make sure, that the class has a default and empty constructor otherwise the process will fail and won't do anything.

Now we can override the virtual Initialize() method and pass the data to the provider through the given helper methods.

using Onsharp.Native;

namespace Tutorial
{
    public class MyPackageProvider : PackageProvider
    {
        protected override void Initialize()
        {
            AddClientScript("script.lua", "-- SOME LUA CODE HERE");
        }
    }
}

We recommend a look into the XML docs or the source of the project to find all the helper methods you can use in order to pass data to the provider. Please keep a look on the first parameter of each of these methods because that is the name of the files and there are some limitations.

Now you just need to tell Onsharp that it should use this provider as your package provider:

using Onsharp.Plugins;

namespace Tutorial
{
    [PluginMeta("PLUGIN_ID", "PLUGIN_NAME", "VERSION", "AUTHOR", PackageProvider = typeof(MyPackageProvider))]
    public class PluginMain : Plugin
    {
        public override void OnStart()
        {
             //Your start up logic here   
        }
        
        public override void OnStop()
        {
            //Your stop and clean up logic here
        }   
    }
}

You just need to add PackageProvider to you PluginMeta and pass the type of your package provider class. Now you can put the plugin onto your server and it should create the package and load it.

The name of the package is either a custom one (therefore you can look onto the base constructor of the base package provider class) or the id of your plugin or the name of your plugin. The priority is as follows: Custom Name > Plugin Name > Plugin ID. The same thing belongs to the version and the author, too.