Struct EntityRef
Read-only entity handle. A ref struct that copies the EntityRecord from the per-archetype LinearHash and provides typed component reads via cached Location ChunkIds. Reads return copies, so the handle stays valid for its whole transaction (#1199).
public ref struct EntityRef- Inherited Members
Remarks
Created by Open / TryOpen on any accessor. It has no write member: writes go through EntityRefMut, returned by
OpenMut / TryOpenMut, which converts implicitly to EntityRef (#997). Must not outlive the creating accessor.
Reads delegate to the EntityAccessor for chunk accessor management.
Properties
ArchetypeId
The archetype ID of this entity.
public readonly ushort ArchetypeId { get; }Property Value
ComponentCount
Number of component slots declared by this entity's archetype. Slots are addressable [0, ComponentCount).
public readonly int ComponentCount { get; }Property Value
Id
The entity's unique identifier.
public readonly EntityId Id { get; }Property Value
IsValid
True if this EntityRef refers to a valid entity.
public readonly bool IsValid { get; }Property Value
Realm
The realm the entity is in (Realms): its cluster's — what an event it emits names as its point's realm (RouteNear(point, realm)). Realm 0
for an archetype without clusters or without a realm key.
public readonly RealmId Realm { get; }Property Value
Methods
GetComponentName(int)
The registered name of the component at slot — matches ComponentTable.Definition.Name (the join key for the schema layout).
Pairs with ReadRaw(int, Span<byte>) for runtime, non-generic component decode.
public readonly string GetComponentName(int slot)Parameters
slotint
Returns
GetComponentSize(int)
The storage size in bytes of the component at slot: the buffer ReadRaw(int, Span<byte>) needs.
public readonly int GetComponentSize(int slot)Parameters
slotint
Returns
IsEnabled(byte)
Check if a component at the given slot is enabled.
public readonly bool IsEnabled(byte slotIndex)Parameters
slotIndexbyte
Returns
IsEnabled<T>(Comp<T>)
Check if a component is enabled by handle.
public readonly bool IsEnabled<T>(Comp<T> comp) where T : unmanagedParameters
compComp<T>
Returns
Type Parameters
T
ReadRaw(int)
The raw storage bytes of the component at slot, copied into a new array: the convenience form of
ReadRaw(int, Span<byte>) for tooling, which allocates once per call. Empty when the slot holds no content.
public readonly ReadOnlySpan<byte> ReadRaw(int slot)Parameters
slotint
Returns
ReadRaw(int, Span<byte>)
Copy the raw storage bytes of the component at slot into destination — the non-generic counterpart to
Read<T>() for tooling that decodes components by field layout at runtime (e.g. the Workbench Data Browser). Returns the number of bytes
copied: the component's storage size (GetComponentSize(int)), or 0 when the slot holds no content. Field values are decoded by the caller
using the component's field offsets. MVCC-correct: Versioned slots resolve to the content visible at the owning transaction's snapshot. Works
regardless of the component's enabled state — query IsEnabled(byte) separately to render disabled components.
A copy for the same reason Read<T>(Comp<T>) is one: a span into the page could outlive it (#1199). Prefer the typed reads whenever the component type is known at compile time.
public readonly int ReadRaw(int slot, Span<byte> destination)Parameters
Returns
Exceptions
- ArgumentException
destinationis shorter than the component.
- See Also
Read<T>()
Read a component by type: a copy, as Read<T>(Comp<T>). Resolves the slot via archetype metadata.
public readonly T Read<T>() where T : unmanagedReturns
- T
Type Parameters
T
Read<T>(Comp<T>)
Read a component by handle: a copy of its value at this handle's snapshot. A copy, not a reference into the page, so nothing this returns can go stale whatever the transaction does next (#1199); zero-copy access is cluster iteration's (ClusterRef<TArch>).
public readonly T Read<T>(Comp<T> comp) where T : unmanagedParameters
compComp<T>
Returns
- T
Type Parameters
T
TryRead<T>(Comp<T>, out T)
Attempt to read a component by handle: a copy, as Read<T>(Comp<T>). Returns false if the component is disabled on this entity.
public readonly bool TryRead<T>(Comp<T> comp, out T value) where T : unmanagedParameters
compComp<T>valueT
Returns
Type Parameters
T
TryRead<T>(out T)
Attempt to read a component by type: a copy, as Read<T>(). Returns false if the archetype doesn't declare the component or it's disabled.
public readonly bool TryRead<T>(out T value) where T : unmanagedParameters
valueT
Returns
Type Parameters
T