Plugin API (Events)

OnLoad()

This event is called one time at server startup.

public override void OnLoad()
{
    Console.WriteLine("Plugin loaded");
}

OnUnload()

This event is called one time at server shutdown.

public override void OnUnload()
{
    Console.WriteLine("Plugin unloaded");
}

OnReload()

This event is when plugin is reloaded (replaced, modified, renamed, added into Plugins folder). To use this feature plugin need to have HotReload flag after PluginClass : Plugin like this Public class PluginClass : Plugin, HotReload - Now server will load and reload this plugin in runtime.

Important: For HotReload plugins you are supposed to design "restart" plugin system during Reload process where it doesn't happen automatically. For example if your plugin spawned NPC entity at OnLoad you have two options:

• Despawn entity with "OnUnload" to spawn it again "OnReload"
• Keep entity spawned and you wont need to call spawn OnReload

public override void OnReload()
{
    Console.WriteLine("Plugin reloaded");
}

OnPacketReceived(PacketEvent)

PacketEvent supports GetPlayer(), GetEndPoint(), GetPacket(), Cancel()

This event is called when server receive packet. This example is showing how to read what player said from text packet.

public override void OnPacketReceived(PacketEvent ev)
{
    var packet = ev.GetPacket();
    
    if (packet is TextMessage textMessage)
    {
        var player = ev.GetPlayer();
        Console.WriteLine($"{player.Username} said {textMessage.Message}");
    }
}

Example below shows how this can be used to prevent specific player from chatting.

public override void OnPacketReceived(PacketEvent ev)
{
    if (ev.GetPacket() is TextMessage textMessage)
    {
        var player = ev.GetPlayer();
        if (mutedPlayer.Contains(player.XUID)) //Why using XUID instead of Username? Players may change their username but XUID can't, it's like account id.
        {
            player.SendMessage("You are muted and can't chat.");
            ev.Cancel(); //So let's ignore and cancel muted player's chat text packet because he is muted.
        }
    }
}

OnPacketSent(PacketEvent)

PacketEvent supports GetPlayer(), GetEndPoint(), GetPacket(), Cancel()

This event is called when server sends packet to player. It's working similar like OnPacketReceived() but you can work with processed packets by server just before they are going to be sent.

Example below is showing how this can be used to add senders username to chat message.

public override void OnPacketSent(PacketEvent ev)
{
    if (ev.GetPacket() is TextMessage textMessage)
    {
        textMessage.Message = $"{textMessage.Username} said {textMessage.Message}"; //let's edit TextMessage packet
        textMessage.Username = "";
    }
}

OnPlayerAttackedEntity(PlayerAttackedEntityEvent)

PlayerAttackedEntityEvent supports GetPlayer(), GetEntity()

This event is called when player is attacking server entities. This example is showing how to print notifiactions about entities that player have attacked.

public override void OnPlayerAttackedEntity(PlayerAttackedEntityEvent ev)
{
    var player = ev.GetPlayer();
    var entity = ev.GetEntity();

    Console.WriteLine($"{player.Username} hit {entity.ActorType}");
}

This is also how you can check if player is clicking on NPCs in server minigames hub.

public override void OnPlayerAttackedEntity(PlayerAttackedEntityEvent ev)
{
    var entity = ev.GetEntity();
    var player = ev.GetPlayer();
    var server = player.CurrentWorld;

    if (server.LevelName == "hub")
    {
        if (entity == hub1.tntRun) //way 1
        {
            //join server
        }
        if (entity.NameTag == "TNT RUN") //another way
        {
            //join server
        }
    }
}

OnPlayerAttackedPlayer(PlayerAttackedPlayerEvent)

PlayerAttackedPlayerEvent supports GetAttacker(), GetVictim()

This event is called when player is attacking other players. This is main event for PvP.

public override void OnPlayerAttackedPlayer(PlayerAttackedPlayerEvent ev)
{
    var attacker = ev.GetAttacker();
    var victim = ev.GetVictim();

    Console.WriteLine($"{attacker.Username} hit {victim.Username}");

    //custom PvP logic for player damage, health etc.
    var heldItem = attacker.Inventory.GetHand() //get item that player is holding.

    if (heldItem is WoodenSword)
    {
        //do some damage
    }
    else if (heldItem is IronSword)
    {
        //do more damage
    }
    else if (heldItem is NetheriteSword)
    {
        //do a lot more damage
        //you can also check item.Data for enchantments if you added some using your custom logic because server doesn't have builtin logic for enchantments
        //and do even more damage or set victim on fire etc.
    }
    else
    {
        //player is holding something else or nothing, do a little damage
    }
}

OnPlayerJoined(PlayerJoinedEvent)

PlayerJoinedEvent supports GetPlayer()

This event is called when player joined the server. This example is showing how to teleport player to specific location like worlds spawn.

public override void OnPlayerJoined(PlayerJoinedEvent ev)
{
    ev.GetPlayer().Teleport(new Vector3(2, -55, -11));
}

OnPlayerLeaved(PlayerLeavedEvent)

PlayerLeavedEvent supports GetPlayer()

This event is called when player leaved the server. Example shows how to send leave message to online players.

public override void OnPlayerLeaved(PlayerLeavedEvent ev)
{
    ev.GetPlayer().CurrentWorld.SendMessage($"{player.Username} Leaved");
}

OnPlayerMove(PlayerMoveEvent)

PlayerMoveEvent supports GetPlayer(), Cancel() (to prevent player from moving)

This event is called every time when player moves, change head rotation. Example shows how to use this to make auto bridge - place block under player.

public override void OnPlayerMove(PlayerMoveEvent ev)
{
    var player = ev.GetPlayer();
    
    player.SendBlock(new DiamondBlock(), player.Position - new Vector3(0, -3, 0)); //player position - player height
}

OnPlayerSentMessage(PlayerSentMessageEvent)

PlayerSentMessageEvent supprots GetPlayer(), GetUncensoredMessage(), GetCensoredMessage(), Cancel()

This event is called when player is sending chat messages.

public override void OnPlayerSentMessage(PlayerSentMessageEvent ev)
{
    var player = ev.GetPlayer();
    var uncensoredMessage = ev.GetUncensoredMessage();

    Console.WriteLine($"{player.Username} said {censoredMessage}");

    //here you can also check if player was using bad language and do ev.Cancel() to prevent players from receiving this message in public server's chat.
}

OnPlayerSkinChanged(PlayerSkinChangedEvent)

PlayerSkinChangedEvent supprots GetPlayer(), GetSkin(), Cancel() (to prevent player from changing skins)

This event is called when player is trying to change their skin. Example below is showing how to prevent player from chaning his skin if skin is not trusted from Minecraft marketplace.

public override void OnPlayerSkinChanged(PlayerSkinChangedEvent ev)
{
    var skin = ev.GetSkin();
    if (!skin.PremiumSkin)
    {
        ev.Cancel();
    }
}