Keen:Entity Component Overview

OFFICIAL CONTENT NOTICE 

OFFICIAL CONTENT

This article contains official content from or verified by the developers at Keen Software House. This information is intended to be accurate at the time it is posted, but may become obsolete over time. If you find errors in this article please describe the errors in the Discussion Page.

Entity components consist of a couple of important methods, and it is important to know what they do and what their intended purpose is.

Version:

0.5

Attributes

Entity Components can be decorated with some attributes which in turn inform the game about important things regarding this entity component. Here follows a non-exhaustive list of Entity Component attributes:

MyComponent
Description: MyComponent attribute marks this class as an Entity Component. The type passed into MyComponent is the save data object builder used for saving data to the world.
Usage: [MyComponent(typeof(MyObjectBuilder_NameOfComponent)]

ReplicatedComponent
Description: ReplicatedComponent attribute marks this Entity Component as relevant for Replication. Required for sending messages across the network.
Usage: [ReplicatedComponent]

Constructor

The class constructor is a core C# feature that is called on each instantiation of the class. This goes for Entity Components as well.
The intended purpose of the constructor should be to initialize variables to their default values. It should never interface with any elements outside the entity component.

Init

The Init method is called when the entity component is initialized externally. This means that certain elements of the game are available.
Additionally, the argument for the Init method is the definition of the entity component. This is the parsed data from the SBC file, converted into a Definition class.

When an entity component is being initialized it is not yet assigned to its parent Entity, and thus the Entity parameter may still be null.
Additionally, when entity components are being initialized, the game may still be loading, and some elements of the game are not yet ready.

You should never interact with any entity components external to this entity component from the Init method.
In many places the game relies on the Init method only being called once. You should never call the Init method from within your code, doing so may cause unpredictable behaviour and instability!

Example:

        private MyNameOfComponentDefinition m_definition = null;

        public override void Init(MyEntityComponentDefinition definition)
        {
            m_definition = definition as MyNameOfComponentDefinition;
        }

Serialize / Deserialize

The Serialize and Deserialize methods are called when the game is being saved or loaded respectively. Serialize returns an object builder which you can receive through base.Serialize(copy). Deserialize receives the object builder from the world and you can read your data from there.
The ObjectBuilder that is used by these methods are specified by the [MyComponent] attribute at the top.

Please be aware that Serialize and Deserialize are not called unless you override IsSerialized and return true.

Example:

        public override bool IsSerialized
        {
            get { return true; }
        }

        public override void Deserialize(MyObjectBuilder_EntityComponent builder)
        {
            base.Deserialize(builder);

            MyObjectBuilder_NameOfComponent myObjectBuilder = builder as MyObjectBuilder_NameOfComponent ;
            m_myImportantVariable = myObjectBuilder.ImportantVariable;
        }

        public override MyObjectBuilder_EntityComponent Serialize(bool copy = false)
        {
            var builder = base.Serialize(copy);

            MyObjectBuilder_NameOfComponent myObjectBuilder = builder as MyObjectBuilder_NameOfComponent ;
            myObjectBuilder.ImportantVariable = m_myImportantVariable;

            return ob;
        }

Warning: Mods with custom object builders

Once a world is saved with a mod with a custom object builder it is currently no longer possible to remove this mod from the world. The game will no longer be able to deserialize the data correctly! This is something we will look into resolving in the future.

OnAddedToScene / OnRemovedFromScene

The OnAddedToScene method is called whenever an entity component's parent entity is finished initializing and is added to the scene. At this point it is safe to interact with the parent Entity as well as other entity components and elements in the game. This is the moment where it is possible to register to events, get references to other components, etc.

OnRemovedFromScene is called right after an entity was taken out of the world. If you registered to any events in OnAddedToScene you should remove them here.

Example:

        public override void OnAddedToScene()
        {
            base.OnAddedToScene();

            // Register for update once every 1000 milliseconds (1 second)
            MyUpdateComponent.Static.AddForUpdate(Update, 1000);
        }

        public override void OnRemovedFromScene()
        {
            base.OnRemovedFromScene();

            // Unregister for updates
            MyUpdateComponent.Static.RemoveFromUpdate(Update);
        }