Entity.md

Friflo.Engine.ECS

Friflo.Engine.ECS

Entity Struct

Represent an object in an EntityStore - e.g. a cube in a game scene.
It is the main API to deal with entities in the engine.
See Example.

public readonly struct Entity :
System.IEquatable<Friflo.Engine.ECS.Entity>

Implements System.IEquatable<Entity>

Remarks

Every Entity has an Id and is a container of Tags, IComponent's, Script's and other child Entity's.

Comparison to other game engines.

• Unity - an Entity provides a similar features set as a GameObject and their ECS Entity.
• Godot - Entity is the counterpart of a Node.
  The key difference is Godot is an OOP architecture inheriting from Node over multiple levels.
• FLAX - Entity is the counterpart of an Actor - an OOP architecture like Godot.
• STRIDE - Entity is the counterpart of a STRIDE Entity - a component based architecture like Unity.
  In contrast to this engine or Unity it has no ECS architecture - Entity Component System.

Components
An Entity is typically an object that can be rendered on screen like a cube, sphere, capsule, mesh, sprite, ... .
Therefore a renderable component needs to be added with AddComponent<T>() to an Entity.

Child entities
An Entity can be added to another Entity using AddChild(Entity).
The added Entity becomes a child of the Entity it is added to - its Parent.
This enables to build up a complex game scene with a hierarchy of Entity's.
The order of children contained by an entity is the insertion order.

Scripts
A Script's can be added to an Entity to add custom logic (script) and data to an entity.
Script's are added or removed with AddScript<TScript>(TScript) / RemoveScript<TScript>().

Tags
Tags can be added to an Entity to enable filtering entities in queries.
By adding Tags to an ArchetypeQuery it can be restricted to return only entities matching the these Tags.

Events
All entity changes - aka mutations - can be observed for specific Entity's and the whole EntityStore.
In detail the following changes can be observed.

type	entity event	event argument	action
component	OnComponentChanged	ComponentChanged	Add, Update, Remove
script	OnScriptChanged	ScriptChanged	Remove, Add, Replace
tags	OnTagsChanged	TagsChanged	AddedTags, RemovedTags
child entity	OnChildEntitiesChanged	ChildEntitiesChanged	Add, Remove

Properties and Methods by category

• general
  Id
  Pid
  Archetype
  Store
  DebugJSON
  
• components · generic
  HasComponent<T>()
  GetComponent<T>() - read / write
  TryGetComponent<T>(T)
  AddComponent<T>()
  RemoveComponent<T>()
  
• components · common
  Name
  Position
  Rotation
  Scale3
  HasName
  HasPosition
  HasRotation
  HasScale3
  
• scripts
  Scripts
  GetScript<TScript>()
  TryGetScript<TScript>(TScript)
  AddScript<TScript>(TScript)
  RemoveScript<TScript>()
  
• tags
  Tags
  AddTag<TTag>()
  AddTags(Tags)
  RemoveTag<TTag>()
  RemoveTags(Tags)
  
• child entities
  Parent
  ChildEntities
  ChildIds
  ChildCount
  AddChild(Entity)
  InsertChild(int, Entity)
  RemoveChild(Entity)
  DeleteEntity()
  GetChildIndex(Entity)
  
• events
  OnTagsChanged
  OnComponentChanged
  OnScriptChanged
  OnChildEntitiesChanged
  DebugEventHandlers
  
• signals
  AddSignalHandler<TEvent>(Action<Signal<TEvent>>)
  RemoveSignalHandler<TEvent>(Action<Signal<TEvent>>)
  EmitSignal<TEvent>(TEvent)
  

Fields
Id
Revision

Properties
Archetype	Returns the Archetype that contains the entity.
ChildCount	Return the number of child entities.
ChildEntities	Return all child entities of an entity.
ChildIds	Return the ids of the child entities.
Components	Return the IComponent's added to the entity.
Data	Returns the entity data used to optimize access of entity components and tags.
DebugEventHandlers	Return event and signal handlers added to the entity.
DebugJSON	Return the JSON representation of an entity.
Enabled	Set entity to enabled/disabled by removing/adding the Disabled tag.
HasName	Returns true if the entity has an EntityName.
HasPosition	Returns true if the entity has a Position.
HasRotation	Returns true if the entity has a Rotation.
HasScale3	Returns true if the entity has a Scale3.
IsNull	Returns true if the entity was deleted.
Name	Returns the EntityName reference of an entity.
Parent	Returns the parent entity that contains the entity.
Pid	Returns the permanent entity id used for serialization.
Position	Returns the Position reference of an entity.
Rotation	Returns the Rotation reference of an entity.
Scale3	Returns the Scale3 reference of an entity.
Scripts	Return the Script's added to the entity.
Store	Returns the EntityStore that contains the entity.
StoreOwnership
Tags	Return the Tags added to the entity.
TreeMembership

Methods
AddChild(Entity)	Add the given entity as a child to this entity. See Example.
AddComponent<T>()	Add a component of the given type T to the entity. See Example. If the entity contains a component of the same type it is updated.
AddComponent<T>(T)	Add the given component to the entity. If the entity contains a component of the same type it is updated. See Example.
AddScript<TScript>(TScript)	Add the given script to the entity. If the entity contains a script of the same TScriptSystem.Type it is replaced. See Example.
AddSignalHandler<TEvent>(Action<Signal<TEvent>>)	Add the given Signal<TEvent> handler to the entity. See Example.
AddTag<TTag>()	Add the given TTag to the entity. See Example.
AddTags(Tags)	Add the given tags to the entity.
Batch()	Returns an EntityBatch to add/remove components or tags to/from this entity using the batch. See Example.
DeleteEntity()	Delete the entity from its EntityStore. The deleted instance is in detached state. Calling Entity methods result in System.NullReferenceException's
DisableTree()	Disable recursively all child entities of the Entity.
EmitSignal<TEvent>(TEvent)	Emits the passed signal event to all signal handlers added with AddSignalHandler<TEvent>(Action<Signal<TEvent>>). See Example.
EnableTree()	Enable recursively all child entities of the Entity.
Equals(Entity)
Equals(object)	Note: Not implemented to avoid excessive boxing.
GetChildIndex(Entity)	Return the position of the given child in the entity.
GetComponent<T>()	Return the component of the given type as a reference.
GetHashCode()	Note: Not implemented to avoid excessive boxing.
GetScript<TScript>()	Get the script of the passed TScriptSystem.Type.
HasComponent<T>()	Return true if the entity contains a component of the given type.
InsertChild(int, Entity)	Insert the given entity as a child to this entity at the passed index.
RemoveChild(Entity)	Remove the given child entity from this entity.
RemoveComponent<T>()	Remove the component of the given type from the entity.
RemoveScript<TScript>()	Remove the script with the given TScriptSystem.Type from the entity.
RemoveSignalHandler<TEvent>(Action<Signal<TEvent>>)	Remove the given Signal<TEvent> handler from the entity.
RemoveTag<TTag>()	Add the given TTag from the entity.
RemoveTags(Tags)	Remove the given tags from the entity.
ToString()
TryGetComponent<T>(T)
TryGetScript<TScript>(TScript)	Gets the script with the passed TScriptSystem.Type.

Events
OnChildEntitiesChanged	Add / remove an event handler for ChildEntitiesChanged events triggered by: AddChild(Entity) InsertChild(int, Entity) RemoveChild(Entity). See Example.
OnComponentChanged	Add / remove an event handler for ComponentChanged events triggered by: AddComponent<T>() RemoveComponent<T>(). See Example.
OnScriptChanged	Add / remove an event handler for ScriptChanged events triggered by: AddScript<TScript>(TScript) RemoveScript<TScript>(). See Example.
OnTagsChanged	Add / remove an event handler for TagsChanged events triggered by: AddTag<TTag>() AddTags(Tags) RemoveTag<TTag>() RemoveTags(Tags). See Example.

Operators
operator ==(Entity, Entity)	Return true if the passed entities have the same Id's.
operator !=(Entity, Entity)	Return true if the passed entities have the different Id's.