Entities

The Entities module provides a base behaviour which can visually appear and disappear over time. The entity keeps a state of visibility, and calls events whenever it changes. Entities can be extremely useful to easily animate anything from puzzle pieces, projectiles or pickups, to user interface screens, health bars or ammo counters.

The Entities module itself only provides the basic functionality. Other modules offer animations and effects that can be applied to any entity.

Within DuskModules, Entities is used by many advanced modules. Anything that can show and hide itself, or be created and destroyed, is an Entity. Modules providing effects can hook into the events fired by Entities, allowing you to use and re-use them for any such object.
Entities has a dependency on the UtilityCollection and the Dynamic Variables modules.

How Entities work

An Entity appears and disappears over time. It starts out hidden. To make it visible:

entity.StartAppearing();

To make it hidden again, call:

entity.StartDisappearing();

Every Entity is connected to an EntityCore on the same object. If none exists, one is automatically created. The EntityCore handles the actual state of visibility for the GameObject, and controls all the other Entities attached to it. This way you can attach any amount of Entities on an object without conflict.

When you call an Entity to appear (or disappear), the call is redirected to the core, which in turn passes it along to all attached Entities. Trigger one Entity, triggers the whole object.

The EntityCore also knows when all Entities are done with appearing or disappearing, which can be instantly, or happens over time. Events are called by the core, to which you can listen to for your own behaviour, to trigger something when it's fully appeared or disappeared.

If you want an Entity to appear or disappear instantly, call:

entity.AppearInstantly();entity.DisappearInstantly();

Finally, if you want an Entity to hide itself instantly, without any effects playing:

entity.HideInstantly();

Create your own Entity

You can create your own Entity scripts by inheriting from Entity.cs.

Override the following methods to add functionality to your custom Entity:

EntityAppearing() is called when the entity starts appearing.
EntityAppeared() is called when the entity has completed appearing.
EntityDisappearing() is called when the entity starts disappearing.
EntityDisappeared() is called when the entity has completed disappearing.
EntityHide() is called when the entity has become hidden for any reason.

Always call the base method, otherwise the Entity state is not set correctly.

The Entity has a few interesting values and features built-in. It has a deltaTime property, which returns either the regular deltaTime, or the unscaledDeltaTime if the entity's transform is a RectTransform, which indicates it's an user interface element. This has been added because it's rare to want your UI to be affected by timescale. Use this deltaTime property for your update method.

An easy way to find out if an Entity should be visible or hidden is the property toVisible. It returns true if the Entity is visible, or is appearing. It returns false if the Entity is disappearing, or hidden. You can use this to set a target value for size or alpha or anything else depending on the Entity's visibility state.

When writing your own Entity script, don't forget to call CompleteAppearing and CompleteDisappearing when it's done.

Entity State

Created, when nothing has happened to it yet.
Appearing, when in progress of showing itself.
Visible, when fully revealed and idle.
Disappearing, when in progress of hiding itself.
Hidden, when fully hidden and idle.

EntityCores

There can be only one EntityCore on a GameObject. If there are more than one, you'll run into errors.

An EntityCore itself is also an Entity, and can also be referenced and called to appear / disappear.

An EntityCore starts out hidden, and disables the object when fully hidden.

The core fires the following events:

onAppearing
onAppeared
onDisappearing
onDisappeared
onHidden
onActivate

There are some variations of EntityCores, which change the default behaviour.

EntityObject

A variation of EntityCore which automatically appears on Awake, instead of staying hidden. When it completes disappearing, it destroys itself.

It can be useful for one-time use entities, such as particles, projectiles or enemies.

However, I recommend using the ObjectPooling module instead of EntityObjects where possible, to save performance.

EntityAlwaysActive

A variation of EntityCore which does not disable or enable the game object based on its state.

Useful for objects that only partially hide themselves, such as indicators that shrink down to a smaller size, or things that fade into the background.

EntitySequence

You can add an EntitySequence to a GameObject in order to call entities on child objects. When the sequence appears, it appears each entity in its list one by one. The same for when it disappears.

With sequences, you can create complicated entity trees, appearing and disappearing many smaller parts of a single object. This can be especially useful for UI Screens with many different panels that pop in one by one.

You need to avoid creating a call loop. Never call an Entity that is higher up the hierarchy than the sequence, unless you're absolutely sure you know what you're doing.

Settings

An EntitySequence has the following values you can set in the Inspector, which define how it plays out the sequence. Each setting exists both for appearing and disappearing:

<>StepDelay. Interval of 1 step
<>Delay. Delay before starting the sequence.
ReverseOn<>. Should it reverse sequence order?

Don't forget to add using DuskModules.Entites; to any script using the module.

Page updated

Report abuse