The EventAPI of Onsharp

On this page we will explain you how to use the event API of Onsharp.

In Onset and Onsharp there are 3 different event types:

1. RemoteEvents : Getting called when a client calls the remote event

2. ServerEvents : Getting called by Onset when something ingame happened

3. CustomEvents : Getting called by Onsharp automatically or manually by a plugin

Remote Events

Remote events are like custom events just that they are called by the clients and the first argument needs to be the calling player, like this:

using Onsharp.Entities;
using Onsharp.Events;
using Onsharp.Plugins;

namespace Tutorial
{
    public class PluginMain : Plugin
    {
        public override void OnStart()
        {
             //Your start up logic here
        }
        
        public override void OnStop()
        {
            //Your stop and clean up logic here
        }  
        
        [RemoteEvent("some-event")]
        public void OnSomeRemoteEvent(Player player)
        {
            //Some logic here
        }
    }
}

The method can than be called by the client by using the CallRemoteEvent function. The parameters are parsed automatically.

Please keep in mind, that the limitations in Onsharp are the same as in Onset. For seeing which types can be used, look over to the Interop page here.

Calling Remote Event

To call a remote event on the client, you just need the player class and call and use the CallRemote function. The first argument is the remote event name and the following arguments are the parameters which will be sent to the client.

Please keep in mind, that the limitations in Onsharp are the same as in Onset. For seeing which types can be used, look over to the Interop page here.

Register Remote Events

By default, any entry points as well as the plugin main class are registered for the event handling. But if you want to make a class, which is neither the plugin main class nor an entry point, can be registered manually. Therefore you just need to call either Server.RegisterRemoteEvents(new EventHolder()) or Server.RegisterRemoteEvents<EventHolder>() both of them can only be called from an entry point class. Please keep one thing in mind: Manually registering of events with the second method will only work with static event handling methods, and with the first one only with non-static ones.

Server Events

We won't talk about all the server events in Onset because this would be a lot of work as well as the events will be updated over time. We will recommend you to look into the Onsharp.Events.EventType enum. The documentation of the enum explains when the event is getting called and which arguments the method signature needs.

We just want to explain how to use the events. To use the events, look for the needed event and its signature, than create the method and mark the method as ServerEvent:

using Onsharp.Entities;
using Onsharp.Events;
using Onsharp.Plugins;

namespace Tutorial
{
    public class PluginMain : Plugin
    {
        public override void OnStart()
        {
             //Your start up logic here
        }
        
        public override void OnStop()
        {
            //Your stop and clean up logic here
        }  
        
        [ServerEvent(EventType.ClientConnectionRequest)]
        public void OnConnectionReq(string ip, int port)
        {
            Logger.Debug("incoming request {IP}:{PORT}", ip, port);
        }
    }
}

Register Server Events

By default, any entry points as well as the plugin main class are registered for the event handling. But if you want to make a class, which is neither the plugin main class nor an entry point, can be registered manually. Therefore you just need to call either Server.RegisterServerEvents(new EventHolder()) or Server.RegisterServerEvents<EventHolder>() both of them can only be called from an entry point class. Please keep one thing in mind: Manually registering of events with the second method will only work with static event handling methods, and with the first one only with non-static ones.

Custom Events

Custom events are Onsharp Runtime only and will be called manually by another plugin or the runtime itself. There is one custom event built in, the CommandFailure event which gets called when a player executed a command wrongly. The use of custom events is the same as with server events but without specifying the EventType but the name of the custom event like this:

using Onsharp.Commands;
using Onsharp.Entities;
using Onsharp.Events;
using Onsharp.Plugins;

namespace Tutorial
{
    public class PluginMain : Plugin
    {
        public override void OnStart()
        {
             //Your start up logic here
        }
        
        public override void OnStop()
        {
            //Your stop and clean up logic here
        }  
        
        [ServerEvent("CommandFailure")]
        public void OnCommandFailure(Player player, CommandFailure failure, string line, string name)
        {
            Logger.Fatal("command failure {FAIL} with {NAME} and {LINE} for {PLAYER}", failure, name, line, player.Name);
        }
    }
}

Calling an Event

To call your own custom event you just can use the runtime interface and call it like this:

bool cancel = Runtime.CallEvent("event-name", "arg1", 2, false);

The first argument is the name of the custom event,. every following argument are the event arguments passed to the method. The call method is returning a bool which identifies a cancel. Look bellow for the explaination of the cancel process.

Register Custom Events

By default, any entry points as well as the plugin main class are registered for the event handling. But if you want to make a class, which is neither the plugin main class nor an entry point, can be registered manually. Therefore you just need to call either Server.RegisterServerEvents(new EventHolder()) or Server.RegisterServerEvents<EventHolder>() both of them can only be called from an entry point class. Please keep one thing in mind: Manually registering of events with the second method will only work with static event handling methods, and with the first one only with non-static ones.

Cancelling Events

There are specific events which can be cancelled. The event handling methods are allowed to return a boolean, and only a boolean. If the methods are returning true, the event gets cancelled. If the methods are returning false, or nothing, the events are not getting cancelled.