Table of Contents

Struct EntityRefMut

Namespace
Typhon.Engine
Assembly
Typhon.Engine.dll

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

ushort

ComponentCount

Number of component slots declared by this entity's archetype. Slots are addressable [0, ComponentCount).

public readonly int ComponentCount { get; }

Property Value

int

Id

The entity's unique identifier.

public readonly EntityId Id { get; }

Property Value

EntityId

IsValid

True if this EntityRef refers to a valid entity.

public readonly bool IsValid { get; }

Property Value

bool

Realm

The realm the entity is in (Realm).

public readonly RealmId Realm { get; }

Property Value

RealmId

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

comp Comp<T>
copy T
field String1024

Type Parameters

T

Exceptions

ArgumentException

field is not a field of copy.

InvalidOperationException

copy names 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

comp Comp<T>
copy T
field ComponentCollection<TElem>

Returns

ComponentCollectionAccessor<TElem>

Type Parameters

T
TElem

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

field is not a field of copy.

InvalidOperationException

copy names 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

comp Comp<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

comp Comp<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

comp Comp<T>
value T

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

slot int

Returns

string

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

slot int

Returns

int

IsEnabled(byte)

Check if a component at the given slot is enabled.

public readonly bool IsEnabled(byte slotIndex)

Parameters

slotIndex byte

Returns

bool

IsEnabled<T>(Comp<T>)

Check if a component is enabled by handle.

public readonly bool IsEnabled<T>(Comp<T> comp) where T : unmanaged

Parameters

comp Comp<T>

Returns

bool

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

slot int

Returns

ReadOnlySpan<byte>

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

slot int
destination Span<byte>

Returns

int

Exceptions

ArgumentException

destination is 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

comp Comp<T>
field String1024

Returns

string

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

comp Comp<T>
field String1024
utf8 Span<byte>

Returns

int

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

comp Comp<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

comp Comp<T>
copy T
field String1024
utf8 ReadOnlySpan<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

comp Comp<T>
copy T
field String1024
text ReadOnlySpan<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

field is not a field of copy.

InvalidOperationException

copy names 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

comp Comp<T>
value T

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

value T

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

comp Comp<T>
value T

Returns

bool

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

value T

Returns

bool

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

entity EntityRefMut

Returns

EntityRef