This document is about: QUANTUM 2
SWITCH TO

Ownership

One of core features in the FPS Template is ownership management. Every Quantum entity has an Owner component, which holds a reference to another entity (i.e. it's EntityRef). Entities created at runtime receive the owner EntityRef as a parameter in the Frame.CreateEntity() method. Scene entities, however, are created with EntityRef.None unless explicitly defined in the EntityComponentOwner in the Unity Editor.

The Frame also contains several methods to operate on the owner entity and it's corresponding parts:

  • GetOwnerEntity(): returns owners EntityRef or EntityRef.None
  • TryGetComponentInOwner<T>(): returns pointer to Quantum component of type T in any owner if it exists, otherwise null. This method behavior is similar to Unity GetComponentInParent<T>(), starts with given entity and iterates recursively on owners chain.
  • TryGetControllerInOwner<T>(): returns EntityController of type T in any owner if the type matches, otherwise null. This method behavior is similar to Unity GetComponentInParent<T>(), starts with given entity and iterates recursively on owners chain. Supports interface.

Example: Get the player actor entity after being hit.

C#

private EntityRef ResolvePlayerActorEntity(Frame frame, HitData hitData)
{
    // We don't know what caused the hit and cannot assume it was an ability / effect / projectile, ...
    // We also don't know exact ownership chain depth
    
    // 1. This solution is fine if the player controls an entity with Agent component, all the time
    return frame.TryGetComponentInOwner<Agent>(hitData.Source, true, out EntityRef agentEntity) != null ? agentEntity : EntityRef.None;
    
    // 2. This solution is fine if the player controls entities with different component set and we can assume each EntityController implements IInputController (player controls the entity with input).
    // This solution will fail if there is an entity with IInputController in the middle of ownership chain (for example a weapon with controller which can reacts to player input)
    return frame.TryGetControllerInOwner<IInputController>(hitData.Source, true, out EntityRef inputControllerEntity) != null ? inputControllerEntity : EntityRef.None;
    
    // 3. This solution is the safest one, but least generic and adds dependency on Player internals
    Player* player = frame.TryGetComponentInOwner<Player>(hitData.Source, false, out EntityRef playerEntity);
    return player != null ? player->ActorEntity : EntityRef.None;
}

In the Unity editor, you can toggle an option Require Owner on the Entity component.

fps template entity require owner toggle
Entity Require Owner Toggle as seen in the Unity Editor.

This option ensures the entity is created after and destroyed before it's owner entity. For example a weapon entity cannot be created if there is no agent and must be destroyed before its owner agent is destroyed.

Back to top