Utility Entity

A Utility Entity represents an object inside a Utility World, and only Utility Entities in the same world can interact with each other. Therefore, if you want a GameObject to be the target of a Utility Agent, you need to do the following:

1. Transform the GameObject into a Utility Entity
2. Register the Utility Entity with the same Utility World as the Utility Agent.

Transforming GameObjects into Utility Entities¶

To transform a GameObject into a Utility Entity, you need to attach these two components to it:

1. Utility Entity Facade

   • It is used to interact with the Utility Entity’s Game Object. For example, Target Filters can access the Entity Facade of both itself and the target to retrieve information from the components of Game Objects in order to check the validity of the target.
     

     public class OtherTeamFilter : TargetFilter
     {
         protected override bool OnFilterTarget(UtilityEntity target)
         {
             if (target.EntityFacade is Character targetCharacter)
             {
                 Character myCharacter = AgentFacade as Character;
                 return myCharacter.Team != targetCharacter.Team;
             }
     
             return false;
         }
     }
     

   • To create your own Entity Facade, you need to create a class inherited from UtilityEntityFacade. For example:
     

     public class ChargeStation : UtilityEntityFacade
     {
         [SerializeField]
         private ChargeStationType type;
     
         [SerializeField]
         private float chargeRadius;
     
         [SerializeField]
         private float chargePerSec;
     
         public ChargeStationType Type => type;
         public float ChargeRadius => chargeRadius;
         public float ChargePerSec => chargePerSec;
     }
     

2. Utility Entity Controller

   • The main role of a Utility Entity Controller is to create and manage the Utility Entity’s lifecycle, including initialization, destruction, registration, and unregistration with utility worlds.
     

Registering Utility Entities¶

To register a Utility Entity with a Utility World, you need to call the Register method of the UtilityEntityController and pass the Utility World as the parameter. For example:

public class AgentsPlacedInSceneDemo : MonoBehaviour
{
    [SerializeField]
    private UtilityWorldController world;

    [SerializeField]
    private List<UtilityAgentController> agents;

    [SerializeField]
    private List<UtilityEntityController> chargeStations;

    private void Start()
    {
        foreach (UtilityAgentController agent in agents)
        {
            agent.Register(world);
        }

        foreach (UtilityEntityController chargeStation in chargeStations)
        {
            chargeStation.Register(world);
        }
    }
}

Getting Utility Entities¶

After being registered with a Utility World, the Utility Entity is allocated an Entity Id. This Id is unique within the world, and you can get the entity from the world by calling UtilityWorldController.GetEntity() and passing the Entity Id as the parameter of the method. For example:

int entityId = entity.Id;  
var entity = world.GetEntity(entityId);

It’s useful in case you want to access the entity from multiple places but don’t want to pass the entity object everywhere.

Entity Lifecycle¶

In v2.2.1, I added these lifecycle event functions to EntityFacade. You can override these functions to receive notifications when lifecycle events occur.

protected virtual void OnRegistered()
{
}

protected virtual void OnActivated()
{  
}

protected virtual void OnEnabled()
{
}

protected virtual void OnDisabled()
{  
}

protected virtual void OnDeactivated()
{
}

protected virtual void OnUnregistered()
{
}

protected virtual void OnDestroyed()
{
}

Additionally, v2.2.1 includes a new example to demonstrate the lifecycle of utility entities:

Since utility entities are managed by a utility world, performing the following actions within action tasks is unsafe because they directly affect the utility world, which is also responsible for running action tasks:

• Register/Unregister utility entities.
• Activate/Deactivate utility entities.
• Enable/Disable utility entities.
• Destroy utility entities.

For safety, you should use these functions inside action tasks instead. They will be queued to run after all action tasks have executed.

• EntityController.Register()
• EntityController.Unregister()
• EntityController.SetActive()
• EntityController.Activate()
• EntityController.Deactivate()
• EntityController.SetEnable()
• EntityController.Enable()
• EntityController.Disable()
• EntityController.Destroy()

Or:

• EntityFacade.Register()
• EntityFacade.Unregister()
• EntityFacade.SetActive()
• EntityFacade.Activate()
• EntityFacade.Deactivate()
• EntityFacade.SetEnable()
• EntityFacade.Enable()
• EntityFacade.Disable()
• EntityFacade.Destroy()

If it is outside of action tasks, you can use these functions instead. They will be run immediately without queueing.

• EntityController.RegisterImmediate()
• EntityController.UnregisterImmediate()
• EntityController.SetEnableImmediate()
• EntityController.EnableImmediate()
• EntityController.DisableImmediate()

Or:

• EntityFacade.RegisterImmediate()
• EntityFacade.UnregisterImmediate()
• EntityFacade.SetEnableImmediate()
• EntityFacade.EnableImmediate()
• EntityFacade.DisableImmediate()

And:

• GameObject.SetActive
• GameObject.Destroy

If you like Utility Intelligence, please consider supporting it by leaving a 5-star review on the Asset Store. Your positive feedback motivates me to keep improving and delivering more updates for this framework.
Thank you so much for your support. I love you all! 🥰