Overriding Entity Factories

On this page we will introduce the procedure to override an entity factory allowing to wrap native entity classes.

What is an Entity Factory?

First of all we need to explain the base concepts of an entity factory. What is it and how exactly does it work? To explain this, we need to clarify what an entity is: An entity is simple said everything in the world of Onset. A vehicle, a player, an object, a pickup, a door, a 3D text and a NPC are all entities. All entities will be represented by the base class Onsharp.Entities.Entity which means that every native class is extending this base class.

Now that you know what an entity is we can explain what the entity factory is. Every entity object gets created once in a lifetime. So Onsharp will create the specific entity object for you, when you need the entity. The entity gets dispossed when the entity is invalid - like destroyed or disconnected. The job of creating the entity takes over the entity factory. The entity factory just creates an instance of the entity and registers it in the entity pool.

What means overriding them and what can I do then?

Overriding an entity factory is a really powerful technique which helps you to develop you plugin object oriented. The big problem of the native entity classes are, that you cannot store data on them without using the property value functionality. To solve this problem, we have implemented the entity factories. You can write your own entity classes via extending the native ones, overriding the entity factories and the Onsharp runtime will use your entity classes instead of the native classes.

For example: You override the native player class, wrap your own class around it, override the specified entity factory and now you can create a command handler with your player class as first argument instead of the native one. Onsharp will take care of the handling and parsing.

How can I implement it?

Its quite simple. All you need is to extend a native entity of your choice, create an own entity factory, let Onsharp know, that it should use your factory and write your code with your own wrapped entity class. In the following steps will we show you, how to do this:

Step 1: Extend the native entity class

using Onsharp.Entities;

namespace Tutorial
{
    public class MyPlayer : Player
    {
        public int MyID { get; }

        public MyPlayer(int id) : base(id)
        {
            // Here you can enter logic to load the players data for example
            MyID = 10;
        }
    }
}

Step 2: Create your own entity factory

using Onsharp.Entities.Factory;

namespace Tutorial
{
    public class MyPlayerFactory : IEntityFactory<MyPlayer>
    {
        public MyPlayer Create(int id)
        {
            return new MyPlayer(id);
        }
    }
}

Step 3: Let Onsharp know to use your entity factory instead

using Onsharp.Plugins;

namespace Tutorial
{
    public class PluginMain : Plugin
    {
        public override void OnStart()
        {
             //Your start up logic here
             Server.OverrideEntityFactory(new MyPlayerFactory());   
        }
        
        public override void OnStop()
        {
            //Your stop and clean up logic here
        }   
    }
}

Now Onsharp will use your entity instead of the native ones like so:

using Onsharp.Plugins;

namespace Tutorial
{
    public class PluginMain : Plugin
    {
        public override void OnStart()
        {
             //Your start up logic here
             Server.OverrideEntityFactory(new MyPlayerFactory());   
        }
        
        public override void OnStop()
        {
            //Your stop and clean up logic here
        }  
        
        [Command("hello")]
        public void OnHelloCommand(MyPlayer player)
        {
            player.SendMessage("Hallo, " + player.Name + "!");
        } 
    }
}