Possessable

MonoBehaviour component placed on entities that can be possessed (characters, NPCs, vehicles). Manages the possession state — tracks the current Possessor, reparents transforms for spatial coupling, executes configurable PossessAction hooks, and fires events on possession/release.

Definition

Namespace: Paragon.Townskeep.PossessionSystem Assembly: Townskeep.dll

public class Possessable : ParagonBehaviour

Inheritance: SerializedMonoBehaviour → ParagonBehaviour → Possessable

Remarks

Possessable is one half of the possession pattern. An entity that can be possessed has a Possessable component; an entity that can possess has a Possessor component. The flow is initiated by the Possessor calling Possess(possessable).

Possession lifecycle

When OnPossessed(possessor) is called:

1. Stores the possessor reference

2. Moves the possessor's GameObject to the possessable's scene

3. Snaps the possessor's position to the possessable's position

4. Parents the possessable's transform under the possessor's transform

5. Executes the possessedAction (if assigned)

6. Fires the Possessed event

When OnReleased(possessor) is called:

1. Clears the possessor reference to null

2. Unparents the possessable's transform (sets parent to null)

3. Executes the releasedAction (if assigned)

4. Fires the Released event

Spatial coupling

While possessed, LateUpdate synchronizes the possessor's position to the possessable's position and resets the possessable's local position to zero. This keeps the possessor physically attached to the possessed entity (e.g., the Player follows the Character).

IPossessable interface

The sibling IPossessable component (e.g., Character) provides the higher-level identity. Possessable.Owner returns the IPossessable, enabling typed queries like possessable.IsPossessedBy<Player>() which checks the possessor's IPossessor owner type.

Quick Lookup

Goal	How
Check if possessed	possessable.IsPossessed()
Check possessor type	possessable.IsPossessedBy<Player>()
Get the possessor	possessable.GetPossessor()
Get typed possessor	possessable.TryGetPossessor<Player>(out var player)

Properties

Owner (internal)

The IPossessable component on the same GameObject. Used internally by the extension methods for typed queries.

internal IPossessable Owner { get; }

Fields

possessedAction

Optional PossessAction executed when this entity is possessed. Configured in the Inspector.

[SerializeField]
private PossessAction possessedAction;

releasedAction

Optional PossessAction executed when this entity is released. Configured in the Inspector.

[SerializeField]
private PossessAction releasedAction;

Events

Possessed

Fires when this entity is possessed.

public event Action<Possessor> Possessed;

Released

Fires when this entity is released from possession.

public event Action<Possessor> Released;

Methods

Awake

Caches the IPossessable component from the same GameObject.

void Awake()

IsPossessed

Returns true if this entity is currently possessed.

public bool IsPossessed()

IsPossessedBy<TPossessor>

Returns true if the possessor's IPossessor.Owner is of type TPossessor.

public bool IsPossessedBy<TPossessor>() where TPossessor : class, IPossessor

GetPossessor

Returns the current Possessor, or null if not possessed.

public Possessor GetPossessor()

TryGetPossessor<TPossessor>

Attempts to get the possessor's IPossessor.Owner as a specific type.

public bool TryGetPossessor<TPossessor>(out TPossessor possessor) where TPossessor : class, IPossessor

OnPossessed

Called by Possessor.Possess(). Sets up spatial coupling, executes the possessedAction, and fires the Possessed event.

public void OnPossessed(Possessor possessor)

Parameter	Type	Description
possessor	Possessor	The possessor taking control

OnReleased

Called by Possessor.Release(). Clears the possessor, unparents, executes the releasedAction, and fires the Released event.

public void OnReleased(Possessor possessor)

Parameter	Type	Description
possessor	Possessor	The possessor releasing control

LateUpdate

Synchronizes the possessor's position to match the possessable's position while possessed. Resets the possessable's local position to zero.

void LateUpdate()

Common Pitfalls

IPossessable required on same GameObject Awake() calls GetComponent<IPossessable>(). If no component implementing IPossessable exists on the GameObject, Owner will be null and typed queries like IsPossessedBy<T>() will throw NullReferenceException.

Transform reparenting on possession OnPossessed() parents the possessable's transform under the possessor's transform. This changes the possessable's local coordinate space. Ensure child transforms and sibling components handle reparenting gracefully.

LateUpdate runs every frame while possessed The position sync in LateUpdate runs unconditionally when possessor != null. For entities possessed long-term (e.g., the player's character), this is expected. The early return when possessor == null prevents unnecessary work.

TryGetPossessor throws if not possessed TryGetPossessor<T>() accesses this.possessor.Owner without null-checking this.possessor. If called when not possessed, it will throw NullReferenceException. Check IsPossessed() first.

See Also

• Possessor — the other half of the possession pattern (the possessing side)

• Player — a concrete IPossessor implementation