Struct EntityRefMut
Writable entity handle: everything EntityRef reads, plus Set<T>(Comp<T>, in 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 Set<T>(Comp<T>, in T) keeps reading the pre-write revision.
Values go in and out by copy (#1199): no member hands out a reference into a page, so a handle stays safe across anything its transaction does next — its cluster base is re-resolved when the accessor that resolved it has let go of the page.
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
Realm
The realm the entity is in (Realm).
public readonly RealmId Realm { get; }
Property Value
Methods
ClearText<T>(Comp<T>, ref T, ref String1024)
Remove the text of the String1024 field field of copy: its chunk is given back, the
handle becomes empty.
public void ClearText<T>(Comp<T> comp, ref T copy, ref String1024 field) where T : unmanaged
Parameters
compComp<T>copyTfieldString1024
Type Parameters
T
Exceptions
- ArgumentException
fieldis not a field ofcopy.- InvalidOperationException
copynames another text than the stored component.
CreateComponentCollectionAccessor<T, TElem>(Comp<T>, ref T, ref ComponentCollection<TElem>)
Open a mutable accessor on a collection field of copy, a copy of comp read from this handle:
var v = e.Read(comp); using (var c = e.CreateComponentCollectionAccessor(comp, ref v, ref v.Items)) { c.Add(x); }
public ComponentCollectionAccessor<TElem> CreateComponentCollectionAccessor<T, TElem>(Comp<T> comp, ref T copy, ref ComponentCollection<TElem> field) where T : unmanaged where TElem : unmanaged
Parameters
compComp<T>copyTfieldComponentCollection<TElem>
Returns
- ComponentCollectionAccessor<TElem>
Type Parameters
TTElem
Remarks
For a Versioned component the new revision is created here, before the accessor exists. That is what makes the buffer shared, so the accessor clones it before changing it. Mutating a copy read before the revision existed would otherwise edit, in place, the buffer the committed revision still points to, and readers of that revision would see the change (#1199).
Every buffer the accessor moves to — the first allocation, a clone, a Replace — is stored into the component at once, and into
field: the collection needs no Set<T>(Comp<T>, in T). Set the copy only for its other fields — it then carries the
same buffer.
Exceptions
- ArgumentException
fieldis not a field ofcopy.- InvalidOperationException
copynames another collection than the stored component: read before the collection last changed.
Disable<T>(Comp<T>)
Disable a component by handle. Stages the change for commit.
public void Disable<T>(Comp<T> comp) where T : unmanaged
Parameters
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 : unmanaged
Parameters
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 : unmanaged
Parameters
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, 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 : unmanaged
Parameters
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
ReadText<T>(Comp<T>, in String1024)
The text of field, a String1024 field of a value of comp read through this handle; empty for no
text.
A value read from a Versioned component reads the text of its own revision (#1094).
public readonly string ReadText<T>(Comp<T> comp, in String1024 field) where T : unmanaged
Parameters
compComp<T>fieldString1024
Returns
Type Parameters
T
ReadText<T>(Comp<T>, in String1024, Span<byte>)
Copies the UTF-8 text of field into utf8 (no terminator) and returns the bytes copied: at most
MaxUtf8Bytes, fewer when utf8 is shorter.
public readonly int ReadText<T>(Comp<T> comp, in String1024 field, Span<byte> utf8) where T : unmanaged
Parameters
compComp<T>fieldString1024utf8Span<byte>
Returns
Type Parameters
T
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 : unmanaged
Returns
- 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 : unmanaged
Parameters
compComp<T>
Returns
- T
Type Parameters
T
SetText<T>(Comp<T>, ref T, ref String1024, ReadOnlySpan<byte>)
The UTF-8 overload of SetText<T>(Comp<T>, ref T, ref String1024, ReadOnlySpan<char>): utf8 ends at its first NUL,
and is cut on a code-point boundary past MaxUtf8Bytes bytes.
public void SetText<T>(Comp<T> comp, ref T copy, ref String1024 field, ReadOnlySpan<byte> utf8) where T : unmanaged
Parameters
compComp<T>copyTfieldString1024utf8ReadOnlySpan<byte>
Type Parameters
T
SetText<T>(Comp<T>, ref T, ref String1024, ReadOnlySpan<char>)
Store text into the String1024 field field of copy, a copy of
comp read from this handle: var v = e.Read(comp); e.SetText(comp, ref v, ref v.Body, "hello");
public void SetText<T>(Comp<T> comp, ref T copy, ref String1024 field, ReadOnlySpan<char> text) where T : unmanaged
Parameters
compComp<T>copyTfieldString1024textReadOnlySpan<char>
Type Parameters
T
Remarks
The text is stored into the entity's component at once, and its handle into field: the text needs no
Set<T>(Comp<T>, in T). Set the copy only for its other fields — it then carries the same handle.
Text longer than MaxUtf8Bytes UTF-8 bytes is cut on a code-point boundary. A Versioned component, or a SingleVersion one under the Commit discipline, gets the new text in a new chunk: readers of the committed value keep reading the old one (#1094).
Exceptions
- ArgumentException
fieldis not a field ofcopy.- InvalidOperationException
copynames another text than the stored component: read before the text last changed.
Set<T>(Comp<T>, in T)
Set a component by handle: value is copied in, and the component's bookkeeping (dirty bit, index shadow, page owed to disk) is done
in the same call. No reference into the page is handed out, so nothing can be written through a stale one (#1199). To change one field, read the
component, change the copy and set it back.
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.
On the component carrying the archetype's [RealmKey], a value whose key differs from the stored one is a realm change, validated
here as Teleport<T>(EntityId, Comp<T>, RealmId, in T) validates it (RM-05): an unregistered, closing or incompatible realm, a Static archetype, or a
non-finite position throws, and nothing is stored.
A ComponentCollection<T> field is not set: the component keeps its collection, which changes through
CreateComponentCollectionAccessor<T, TElem>(Comp<T>, ref T, ref ComponentCollection<TElem>) alone. An empty handle in value is ignored; one naming another buffer
throws.
public void Set<T>(Comp<T> comp, in T value) where T : unmanaged
Parameters
compComp<T>valueT
Type Parameters
T
Exceptions
- InvalidOperationException
A realm change the entity cannot make, or a value naming a collection buffer the entity does not hold.
Set<T>(in T)
Set a component by type: as Set<T>(Comp<T>, in T), resolving the slot via archetype metadata.
public void Set<T>(in T value) where T : unmanaged
Parameters
valueT
Type Parameters
T
Exceptions
- InvalidOperationException
A realm change the entity cannot make.
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 : unmanaged
Parameters
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 : unmanaged
Parameters
valueT
Returns
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