Entity

Namespace Mc.Scripting · Kind struct (readonly)

public readonly struct Entity : IEquatable<Entity>

Handle to an ECS entity (flecs id). Blittable: usable directly in events and components.

Remarks

Refs returned by Entity.Get point into ECS storage and are invalidated by structural changes (adding/removing components, destroying entities). Don’t keep them.

A handle stays valid as a value forever; whether the entity behind it is alive is a separate question (IsAlive). Operations on a dead handle fail (Get<T> throws, Has<T> is false).

Examples

Working with components

public struct Mana { public int Value; }

// in OnEnable:
Ecs.RegisterComponent<Mana>("hello:mana");

// in an event handler, where e is a PlayerJoinEvent:
Entity player = e.Player;                             // a Player converts to its Entity
player.Set(new Mana { Value = 10 });                  // add or overwrite
if (player.Has<Mana>()) player.Get<Mana>().Value--;   // in-place edit through a ref
if (player.TryGet<Mana>(out var copy)) Log.Info($"mana {copy.Value}");
player.Remove<Mana>();

Constructors

Member	Description
Entity(ulong id)	Wraps an entity id.

Constructor

public Entity(ulong id)

Wraps an entity id.

Parameters

Name	Type	Description
id	ulong

Fields

Member	Description
readonly ulong Id	The flecs entity id (index and generation); 0 is the null entity.

Id

public readonly ulong Id;

The flecs entity id (index and generation); 0 is the null entity.

Properties

Member	Description
bool IsAlive { get; }	Whether the entity exists.
bool IsGameEntity { get; }	Whether this is an entity of the game world (a player, mob, item, orb, projectile …) as opposed to a bare ECS entity.
bool IsNull { get; }	Whether this is the null entity.
Location Location { get; }	The location of a game entity.
string TypeKey { get; }	The entity type key of a game entity ("minecraft:zombie", "minecraft:item", "minecraft:player"), empty for a stale handle or an entity that is not a game entity (one created with Entity.Spawn).
static Entity Null { get; }	The null entity.

IsAlive

public bool IsAlive { get; }

Whether the entity exists. A destroyed entity’s id goes stale (the generation no longer matches).

IsGameEntity

public bool IsGameEntity { get; }

Whether this is an entity of the game world (a player, mob, item, orb, projectile …) as opposed to a bare ECS entity.

IsNull

public bool IsNull { get; }

Whether this is the null entity.

Location

public Location Location { get; }

The location of a game entity.

Throws

• System.InvalidOperationException: The handle is stale or the entity is not a game entity.

TypeKey

public string TypeKey { get; }

The entity type key of a game entity ("minecraft:zombie", "minecraft:item", "minecraft:player"), empty for a stale handle or an entity that is not a game entity (one created with Entity.Spawn).

Null

public static Entity Null { get; }

The null entity.

Methods

Member	Description
bool Despawn()	Removes a game entity from the world without any death logic (no drops, no death event): items, orbs, mobs, projectiles.
void Destroy()	Destroys an entity created with Entity.Spawn.
bool Equals(Entity other)	Same entity id.
override bool Equals(object? obj)	Same entity id.
ref T Get<T>() where T : unmanaged	Reference to component T; throws if the entity lacks it.
override int GetHashCode()	Hash of the id.
NbtCompound? GetNbt()	The data of a game entity as /data get entity shows it (position, motion, health, name, item, …).
ref T GetOrAdd<T>() where T : unmanaged	Reference to the component, adding it (zero-initialised) when missing.
bool Has<T>() where T : unmanaged	Whether the entity has component T.
bool Kill()	Kills a living entity the way the /kill command does (generic kill damage: death events, drops and the death animation); other entities are removed.
Entity Remove<T>() where T : unmanaged	Removes a component.
Entity Set<T>(in T value) where T : unmanaged	Sets (adds or overwrites) a component value.
bool SetGlowingFor(Player viewer, bool glowing)	Makes this entity (a player or a mob) glow for one viewer: the viewer sees the glowing outline on it, the other players do not.
bool SetNbt(NbtCompound data, bool merge = true)	Changes the data of a game entity like /data merge entity.
bool Teleport(Location location)	Moves a game entity.
override string ToString()	Debug text.
bool TryGet<T>(out T value) where T : unmanaged	Copies the component if present.
bool TryGetLocation(out Location location)	Where a game entity is.
ref T TryGetRef<T>() where T : unmanaged	Pointer-style access: a null ref (check with Unsafe.IsNullRef) when absent.
static Entity Spawn()	Creates an empty ECS entity (not a game entity).

Despawn

public bool Despawn()

Removes a game entity from the world without any death logic (no drops, no death event): items, orbs, mobs, projectiles. Players cannot be removed (use Player.Kick).

Returns bool: True when the entity was removed (it disappears for the clients at the next tick).

Destroy

public void Destroy()

Destroys an entity created with Entity.Spawn. Does nothing for the null entity or a stale handle. Entities of the game (players, mobs, items, anything an event or a handle hands out) are not the plugin’s to destroy: the call is ignored with a warning (use the game APIs, e.g. Player.Kick).

Equals

public bool Equals(Entity other)

Same entity id.

Parameters

Name	Type	Description
other	Entity

Returns bool

Equals

public override bool Equals(object? obj)

Same entity id.

Parameters

Name	Type	Description
obj	object?

Returns bool

Get<T>

public ref T Get<T>() where T : unmanaged

Reference to component T; throws if the entity lacks it. For a component the game registered itself (bound by its engine name) the reference points at a COPY: engine components are read only for plugins, writing through it changes nothing.

Returns ref T

GetHashCode

public override int GetHashCode()

Hash of the id.

Returns int

GetNbt

public NbtCompound? GetNbt()

The data of a game entity as /data get entity shows it (position, motion, health, name, item, …).

Returns NbtCompound?: A copy, or null for a stale handle or an entity without a save form.

GetOrAdd<T>

public ref T GetOrAdd<T>() where T : unmanaged

Reference to the component, adding it (zero-initialised) when missing.

Returns ref T

Has<T>

public bool Has<T>() where T : unmanaged

Whether the entity has component T.

Returns bool

Kill

public bool Kill()

Kills a living entity the way the /kill command does (generic kill damage: death events, drops and the death animation); other entities are removed.

Returns bool: True when something happened.

Remove<T>

public Entity Remove<T>() where T : unmanaged

Removes a component.

Returns Entity

Set<T>

public Entity Set<T>(in T value) where T : unmanaged

Sets (adds or overwrites) a component value.

Parameters

Name	Type	Description
value	in T

Returns Entity

SetGlowingFor

public bool SetGlowingFor(Player viewer, bool glowing)

Makes this entity (a player or a mob) glow for one viewer: the viewer sees the glowing outline on it, the other players do not. The colour is the vanilla white (no team colour). The glow ends with glowing = false, with the entity, or with the plugin.

Parameters

Name	Type	Description
viewer	Player	The player who sees the outline.
glowing	bool	Whether it glows for the viewer.

Returns bool: False when the engine refused it (the entity is not tracked, or the glow table is full).

SetNbt

public bool SetNbt(NbtCompound data, bool merge = true)

Changes the data of a game entity like /data merge entity. Players cannot be edited this way (use the player API).

Parameters

Name	Type	Description
data	NbtCompound	The data.
merge	bool = true	True merges into the current data (the usual choice); false replaces the editable data with the compound.

Returns bool: True when the entity took the data.

Teleport

public bool Teleport(Location location)

Moves a game entity. Players go through Player.Teleport (with its event); mobs, items and the like move silently, within their dimension.

Parameters

Name	Type	Description
location	Location	The destination.

Returns bool: True when the entity moved.

ToString

public override string ToString()

Debug text.

Returns string

TryGet<T>

public bool TryGet<T>(out T value) where T : unmanaged

Copies the component if present.

Parameters

Name	Type	Description
value	out T

Returns bool

TryGetLocation

public bool TryGetLocation(out Location location)

Where a game entity is.

Parameters

Name	Type	Description
location	out Location	The world, position and rotation.

Returns bool: False for a stale handle or a bare ECS entity.

TryGetRef<T>

public ref T TryGetRef<T>() where T : unmanaged

Pointer-style access: a null ref (check with Unsafe.IsNullRef) when absent.

Returns ref T

Spawn

public static Entity Spawn()

Creates an empty ECS entity (not a game entity).

Returns Entity

Operators

Member	Description
static bool operator !=(Entity a, Entity b)	Different entity id.
static bool operator ==(Entity a, Entity b)	Same entity id.

operator !=

public static bool operator !=(Entity a, Entity b)

Different entity id.

Parameters

Name	Type	Description
a	Entity
b	Entity

Returns bool

operator ==

public static bool operator ==(Entity a, Entity b)

Same entity id.

Parameters

Name	Type	Description
a	Entity
b	Entity

Returns bool

See also

Location · NbtCompound · Player