Entity Destroy Events

Summary

Shows how to use the Entity.OnDestroy event on the client to prevent the entity's game object from being destroyed when the entity is destroyed, and add custom destroy logic based on the reason the entity was destroyed. You could use this to play a death animation when a character dies, or turn them into a ragdoll controlled by local physics.

Description

Entity OnDestroy fires on the client when the entity is destroyed for any reason. It has one parameter which is an enum indicating the reason the entity was destroyed, which can be any of the following:

• SERVER_DESTROY The server destroyed the entity.

• SYNC_GROUP_REMOVAL The entity stopped syncing because it is in a sync group the player is not added to.

• INVALID_PLAYER_SPAWN The local player sent a request to spawn the entity and the server denied the request.

• IDLE_CONNECT The client's connection state became idle.

• DISCONNECT The client disconnected.

By default, the entity's game object is destroyed when the entity is destroyed, unless it was a scene entity (an entity whose game object was part of the initial scene), then its game object is disabled so it can be reused if the entity spawns again. You can prevent this from happening by setting Entity.DestroyWithServer = false; or unchecking 'Destroy With Server' in the ksEntityComponent inspector. If you prevent the game object from being destroyed, you should call ksEntityComponent.CleanUp() when you no longer need the game object, which will destroy or disable the game object if the belonged to a scene entity. If you know the game object did not belong to a scene entity, you can just destroy the game object instead of calling ksEntityComponent.CleanUp().

*ksEntityComponent.CleanUp() calls ReleaseGameObject() on the Entity Factory that created the game object. The default factory destroys the entity.

When the entity is destroyed, all client entity scripts have their Detached() method called and are disabled, and their Entity and Room references are set to null. For this reason, any update logic you need to run after the entity is destroyed should be in a regular MonoBehaviour instead of a ksEntityScript.

The following script shows how to register an entity OnDestroy event and prevent the game object from being destroyed.

using KS.Reactor.Client.Unity;
using KS.Reactor.Client;
using KS.Reactor;

public class ceDestroyHandler : ksEntityScript
{
    // Called after all other scripts/entities are attached/spawned.
    public override void Initialize()
    {
        Entity.OnDestroy += HandleDestroy;
    }

    // Called when the script is detached.
    public override void Detached()
    {
        Entity.OnDestroy -= HandleDestroy;
    }

    private void HandleDestroy(ksDestroyReason reason)
    {
        if (reason == ksDestroyReason.SERVER_DESTROY)
        {
            ksLog.Debug(this, "Server destroyed the entity.");
            Entity.DestroyWithServer = false;// Prevent the game object from being destroyed.

            // Add your destroy logic here. You could play a death animation, or turn a character into a ragdoll.
        }
        else if (reason == ksDestroyReason.SYNC_GROUP_REMOVAL)
        {
            ksLog.Debug(this, "Entity stopped syncing because it is in a sync group the player in not added to.");
            Entity.DestroyWithServer = false;// Prevent the game object from being destroyed.

            // Add your destroy logic here. You could use a Monobehaviour to fade-out the entity.
        }
        // For all other destroy reasons (such as disconnects), do not set Entity.DestroyWithServer = false to let the
        // game object be destroyed.
    }
}