Actor lifecycle

An actor will go through a series of phases during its lifetime. It is important to know which phases exist and what you can and can not do during these phases.

The phases applies both to the actor and components within actors. Each phase applies to all components before the next phase starts.

1. Construction

   • The class is instantiated and the constructor is called.

   • Services are injected and components are attached using the functions inject and attach.

   • Don’t use properties on the class that are parameters as their values will be undefined.

2. Deserialisation

   • Properties set using the attach function or Attach decorator are set.

   • Parameters configured in the editor are set on the actor and components.

3. Initialisation

   • The onInit method is called on the actor and then on components.

   • OnInit methods can be asynchronous and will run at the same time. Therefore, avoid being dependent on any logic to have happened in another component’s onInit method as the order in which they complete may not be reliable.

   • Do use parameter properties on the class as they are now defined.

   • Do set up subscriptions and start performing game logic.

   • Do dynamically attach components if they can’t be attached during the construction phase. Use this.attach

   • Don’t use the functions inject or attach.

4. Begin play

   • This happens when an actor is spawned in the world.

   • The onBeginPlay method is called on the actor and then on components. This does not happen inside the editor.

   • Use this phase to start game play functionality.

5. Update

   • The onUpdate method is called before every frame is rendered and is commonly used for logic.

   • Do perform functionality that may need to transform rendered objects or other visual effect.

   • Avoid creating creating new objects that are only used within this function. Because this function is run with such high frequency, memory allocation and its garbage collection can end up having a significant performance impact.

   • Avoid using the update phase for functionality that can run with a different frequency than the render loop frequency. Synchronising functionality between different actors can be difficult as the order in which the onUpdate method is called is not guaranteed to be consistent between actors. Instead, rely on events emitted from other actors, components or systems.

6. Late update

   1. The onLateUpdate method is also called once per frame but is called after all onUpdate methods have been called.

   2. It can be useful when you want to ensure that all onUpdate functions have finished before executing certain code.

   3. Common use cases for onLateUpdate include camera manipulation or following, especially when the camera is following a moving object that has been updated in the onUpdate method.

7. End play

   • This happens when the game shuts down or the actor is removed.

   • The onEndPlay method is called on the actor and then on components. This does not happen inside the editor.

8. Removal

   1. The actor is removed from the world and is disposed.

   2. Unsubscribe on all subscriptions created. If you are using RxJs to create subscriptions, use .pipe(takeUntil(this.disposed)) to automatically unsubscribe when the actor is removed.