Struct EntityRefMut
Writable entity handle: everything EntityRef reads, plus Write<T>(Comp<T>), Enable<T>(Comp<T>) and
Disable<T>(Comp<T>). Returned by OpenMut / TryOpenMut on every accessor; Open / TryOpen return the read-only
EntityRef, which has no write member at all — writing through a read-only open does not compile (#997).
public ref struct EntityRefMut- Inherited Members
Remarks
Holds one EntityRef and no other state: read members forward to it, write members work on its fields. A writable resolve fetches
the entity's cluster page with GetChunkAddress(…, dirty: true) and has run the accessor's mutation prep (EnsureMutable + InProgress
for a Transaction) — the preconditions the write paths below rely on.
Converts implicitly to EntityRef, so read-only helpers take an EntityRef. The conversion copies: a Versioned slot resolved on the copy is not memoized back here, and a copy taken before a Versioned Write<T>(Comp<T>) keeps reading the pre-write revision.
Must not outlive the creating accessor.
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
Methods
Disable<T>(Comp<T>)
Disable a component by handle. Stages the change for commit.
public void Disable<T>(Comp<T> comp) where T : unmanagedParameters
compComp<T>
Type Parameters
T
Enable<T>(Comp<T>)
Enable a component by handle. Stages the change for commit.
public void Enable<T>(Comp<T> comp) where T : unmanagedParameters
compComp<T>
Type Parameters
T
Enable<T>(Comp<T>, in T)
Supplies a value for a component and enables it, in one step.
public void Enable<T>(Comp<T> comp, in T value) where T : unmanagedParameters
compComp<T>valueT
Type Parameters
T
Remarks
The complement to Enable<T>(Comp<T>), not a replacement for it. The no-value overload re-enables a component that already has one — disabling preserves the payload, so a disable/enable round trip needs no value and must not demand one. This overload exists for the case that overload refuses: a component the spawn never supplied, which has no value to enable. Write is gated by the same EnabledBits as Read, so a caller cannot set the value first; enabling and supplying have to happen together (#845).
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) for runtime, non-generic component decode.
public readonly string GetComponentName(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)
Read the raw storage bytes of the component at slot — the non-generic counterpart to Read<T>() for tooling that decodes
components by field layout at runtime (e.g. the Workbench Data Browser). The returned span points directly into mapped page / cluster memory (zero-copy)
and is valid only while this EntityRef is alive. Its length is the component's storage size; 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.
Prefer the typed Read<T>() / TryRead<T>(out T) whenever the component type is known at compile time — they return a typed (zero-copy) ref with no manual offset decoding. Reach for ReadRaw(int) only when the component type is not available statically.
public readonly ReadOnlySpan<byte> ReadRaw(int slot)Parameters
slotint
Returns
Read<T>()
Read a component by type. Resolves slot via archetype metadata.
public readonly ref readonly T Read<T>() where T : unmanagedReturns
- T
Type Parameters
T
Read<T>(Comp<T>)
Read a component by handle. Zero-copy — returns a ref into the chunk page (or cluster slot).
public readonly ref readonly T Read<T>(Comp<T> comp) where T : unmanagedParameters
compComp<T>
Returns
- T
Type Parameters
T
TryRead<T>(out T)
Attempt to read a component by type. Returns false if the archetype doesn't declare the component or it's disabled.
Returns a copy (not ref) since out parameters can't be ref readonly.
For zero-copy, use if (entity.IsEnabled(comp)) { ref readonly var v = ref entity.Read(comp); }.
public readonly bool TryRead<T>(out T value) where T : unmanagedParameters
valueT
Returns
Type Parameters
T
Write<T>()
Write a component by type. Resolves slot via archetype metadata. For Versioned: copy-on-write (allocates new chunk, preserves old for concurrent readers). For SingleVersion with indexes: shadows old field values on first write per tick for deferred index maintenance.
public ref T Write<T>() where T : unmanagedReturns
- T
Type Parameters
T
Write<T>(Comp<T>)
Write a component by handle. Returns a mutable ref into the chunk page (or cluster slot). For Versioned: copy-on-write (allocates new chunk, preserves old for concurrent readers). For SingleVersion with indexes: shadows old field values on first write per tick for deferred index maintenance.
public ref T Write<T>(Comp<T> comp) where T : unmanagedParameters
compComp<T>
Returns
- T
Type Parameters
T
Operators
implicit operator EntityRef(in EntityRefMut)
Read-only view of the same entity. A copy — see the type remarks.
public static implicit operator EntityRef(in EntityRefMut entity)Parameters
entityEntityRefMut