LEGACY: Event Hooking, Subscriptions, and Publishing

Overview

Event Hooking is the process by which scripts are called to our C# code base. There's a couple of ways to do this depending on what you're working on. We'll go over both types.

Method 1 - Hooking Events on an Object

This style of event hooking is very similar to what you're probably used to in the toolset. When you want a script to fire on a specific event - such as the OnDamaged event of a placeable - you need to assign a script to it. The difference is that the same set of scripts are used every time, with the C# script getting stored as a local variable on the object.

Take this example. We set the OnDamage event to "script_1".

Note: You won't find "script_1" in the module. This is okay. The server will reach out to the C# code and find it there, instead.

Now that we have the script set, we need to go to the Advanced tab and click on the Variables button near the bottom. This can be found here.

This will pop up a new window. You need to add a variable named "SCRIPT_1" of type "string" with the path to the script you wish to execute. For this example, we'll target the GenericConversation script found in the Placeable namespace.

Here's what it should look like when you're done (don't forget to click ADD).

Hit OK a couple times, save the module, and now your placeable will run the GenericConversation script any time it's damaged.

Up to 9 different scripts can be attached to a single object. Simply add "script_2" to the event and set a "SCRIPT_2" variable on the object.

Method 2 - Subscribing to an Event in Code

If you're able to hook an event using method #1, you should do that. However, there will be times where you're working on a system and it makes more sense to do the hooks in C# instead. This is a little more technical and only recommended if you know what you're doing.

When the server boots, the entire code base is searched for all methods called SubscribeEvents and then executes them. This means the only thing you need to do is make a public SubscribeEvents methods in whatever class you're working on.

Inside this SubscribeEvents method you'll hook whatever event you want and run the code you specify.

Take a look at this example for more info on how this works.

using System;
using SWLOR.Game.Server.Event.Module;
using SWLOR.Game.Server.Messaging;

namespace SWLOR.Game.Server.MyNamespace
{
    public static class Testing
    {
        // This method is automatically picked up when the module loads. Simply create it and then
        // subscribe to any events you wish to listen to.
        // Don't do anything other than event subscriptions here. You will get unreliable results.
        public static void SubscribeEvents()
        {
            // This statement means "When the module loads, execute the MyMethod method.
            MessageHub.Instance.Subscribe<OnModuleLoad>(msg => MyMethod());
        }

        // This is the method we'll execute when the module loads.
        private static void MyMethod()
        {
            // If everything goes well, this message will display in the console when the module loads.
            Console.WriteLine("Hello module load.");
        }
    }
}

Please be aware that you cannot guarantee the order in which subscribed events will execute. If order is important, you'll want to publish an event and subscribe to that instead. Speaking of which...

Method 2 - Publishing an Event

You can also publish a custom event very easily. Create a new class in the Event folder. For this example, we'll use "OnAreaInstanceCreated". This class will be very simple.

using SWLOR.Game.Server.GameObject;

namespace SWLOR.Game.Server.Event.SWLOR
{
    public class OnAreaInstanceCreated
    {
        public NWArea Instance { get; set; }

        public OnAreaInstanceCreated(NWArea instance)
        {
            Instance = instance;
        }
    }
}

This is a plain old C# object. You can put whatever properties you want in here - just don't forget to transfer it during the next step.

Now that we have our event it's time to publish it. You'll want to execute the following line when it's time to publish the event. Take a look at the next example.

// Assume GetInstance is implemented and retrieves a new area instance.
NWArea instance = GetInstance();

// This will publish a new OnAreaInstanceCreated event, passing in the instanced area.
MessageHub.Instance.Publish(new OnAreaInstanceCreated(instance));

Then, when you want to subscribe to this event it's done just like before except this time we're passing the instance property to the method.

public static void SubscribeEvents()
{
    MessageHub.Instance.Subscribe<OnAreaInstanceCreated>(msg => ProcessInstance(msg.Instance));
}

private static void ProcessInstance(NWArea instance)
{
    // <Processing code>
}

And that's all there is to it!