Table of Contents

Build diagnostics

The Typhon package ships Roslyn analyzers and source generators that run in your compilation: referencing the package is enough, there is nothing to configure. They catch, at build time, mistakes that Typhon would otherwise report late (at open, on the first spawn) or never. Typhon.Protocol, which Typhon and Typhon.Client both depend on, ships the replication generator and TYPHON015.

⚠️ Analyzers reach the project that references the package directly. NuGet does not flow analyzers through a project reference or a package dependency (PrivateAssets defaults to contentfiles;analyzers;build). Declare components, archetypes and systems in the project that has <PackageReference Include="Typhon" … />, or add the reference to the project that declares them.

Each ID below is the target of the help link your IDE shows next to the diagnostic.

ID Severity Package Catches
TYPHON001 Error Typhon a no-copy type passed by value or in
TYPHON003 Error Typhon a no-copy type copied
TYPHON004 Error Typhon a must-dispose value never disposed
TYPHON005 Error Typhon a type holding a must-dispose field without a Dispose()
TYPHON006 Error Typhon a Dispose() that skips a must-dispose field
TYPHON007 Error Typhon an early return in Dispose() that skips a must-dispose field
TYPHON009 Warning Typhon a spatial component written through a span instead of WriteSpatial
TYPHON010 Warning Typhon a component struct storing avoidable padding
TYPHON011 Error Typhon a component whose managed and marshalled layouts differ (bool, char)
TYPHON012 Error Typhon a non-readonly EntityRef/EntityRefMut member called on a read-only receiver
TYPHON013 Warning Typhon a component too large to pass to Spawn
TYPHON016 Warning Typhon an await inside a transaction's scope
TYPHON017 Warning Typhon Where(Func) over an [Index] field, which scans every entity
TYPHON015 Warning Typhon.Protocol a command sent by name while its typed struct is in reach
TPH1001–TPH1004 Error Typhon invalid cascade graphs and archetype declarations
TPH1101–TPH1109 Error Typhon.Protocol invalid replication declarations

Ownership: no-copy and must-dispose types

Some Typhon types own pinned pages or an epoch scope: Transaction, UnitOfWork, BulkLoadSession, ClusterEnumerator<T>, the collection and index enumerators. Copying one duplicates what it holds; dropping one undisposed keeps its pages pinned and its epoch held, which stalls page eviction and the checkpoint. A type of yours that holds one by value inherits the rule.

TYPHON001 — no-copy parameter not passed by ref

A parameter of a no-copy type (for example ClusterEnumerator<T>) is taken by value or in. By value copies it; in makes the compiler copy it before every non-readonly call. Fix: declare the parameter ref. A code fix is offered in the IDE.

TYPHON003 — no-copy value copied

A no-copy value is assigned to another variable, returned or passed by value. Fix: work through a ref local or a ref parameter.

TYPHON004 — must-dispose value never disposed

A Transaction, UnitOfWork, enumerator or other must-dispose value is created and not disposed on every path. An undisposed transaction keeps its epoch pinned: memory reclamation and the checkpoint wait behind it. Fix: using var tx = db.CreateQuickTransaction();. A code fix is offered.

TYPHON005 — owner without Dispose()

Your type holds a must-dispose value in a field and has no Dispose(), so nothing ever releases it. Fix: implement IDisposable (or, on a ref struct, a Dispose() method) and dispose the field.

TYPHON006 — Dispose() skips a field

Dispose() exists but does not dispose every must-dispose field. Fix: dispose each of them.

TYPHON007 — early return skips a field

A return in Dispose() exits before a must-dispose field is disposed. Fix: dispose the fields before any early return, or restructure.

Components and entity handles

TYPHON009 — spatial component written through a span

ClusterRef.GetSpan<T> / Get<T> on a component carrying a [SpatialIndex] field. Writes through it bypass the WriteSpatial barrier, so the engine falls back to a scan of every dirty slot to keep the spatial index right. Fix: cluster.WriteSpatial(Arch.Comp, slot, value); for a read, use GetReadOnlySpan / GetReadOnly.

TYPHON010 — avoidable padding

A component column is strided by sizeof(T): alignment padding is stored for every entity, logged to the WAL and checkpointed. A single long or double rounds the struct up to a multiple of 8. Fix: [StructLayout(LayoutKind.Sequential, Pack = 4)]. Pack moves field offsets, which are persisted: on a component that already has data, use Size instead (or bump the revision).

TYPHON011 — managed and marshalled layouts differ

A bool is 1 byte managed and 4 marshalled; a char is 2 and 1. When a field's offset differs between the two layouts, every field-addressed path (index keys, WAL field decode, recovery, schema evolution, tools) reads the wrong bytes, with no error anywhere. Fix: byte for a flag, ushort for a code unit.

TYPHON012 — hidden defensive copy of an entity handle

A non-readonly member of EntityRef / EntityRefMut (Set, Enable, …) is called on a read-only receiver (in parameter, readonly field): the compiler copies the handle first, and any state the call updates is lost with the copy. Fix: pass the handle by ref, or hold it in a non-readonly local.

TYPHON013 — component too large to pass to Spawn

Spawn carries component values inline in 112 bytes. A larger component cannot be passed to it. Fix: split the component (a large key and its payload are usually two components), or spawn without it and write it through OpenMut in the same transaction — then suppress the warning with a reason.

TYPHON016 — await inside a transaction's scope

An await between a Transaction's creation and its disposal, in the same method. A transaction belongs to the thread that created it — it holds that thread's epoch scope — and the continuation of an await resumes on another thread in an ASP.NET host, where its Commit, Rollback and Dispose throw (rule EP-04). Fix: finish the transaction before awaiting, or create it after; do the slow I/O outside its scope.

Queries

TYPHON017 — Where(Func) over an indexed field

tx.Query<PlayerArch>().Where<Player>(p => p.Level > 10) where Level carries [Index]. Where takes an opaque delegate: the query opens every entity it admits and calls the predicate on each, so the index is never used. Fix: WhereField<Player>(p => p.Level > 10) — same lambda, parsed into an index seek or range. The code fix rewrites the call when the whole predicate is comparisons on [Index] fields joined by &&; for anything else (two fields compared, a computed value, a non-indexed field, ||) narrow with WhereField on the indexed part and keep Where for the rest. A delegate passed as a variable or method group is not analyzed.

Subscriptions clients

TYPHON015 — command sent by name

TyphonClient.SendCommandAsync("MoveCmd", values) while the [ReplicatedMessage] struct MoveCmd is in reach. The name-keyed path finds fields by string at run time and allocates per send. Fix: send it typed: client.Enqueue(in cmd) then await client.FlushCommandsAsync() — fields checked at compile time, bound to the negotiated catalog once.

Source generator diagnostics

TPH1001 — cascade-delete cycle

An OnParentDelete = Cascade graph loops back on itself. Fix: break the cycle; cascades must form a tree.

TPH1002 — cascade-delete diamond

An archetype is reachable through two cascade paths. Fix: keep one cascading path; make the other a plain reference.

TPH1003 — unique index with an ambiguous scope

Several archetypes of one inheritance tree declare the component carrying a unique [Index]; each would own a separate tree, so uniqueness between them cannot be enforced. Fix: declare the component on their common ancestor, or use [Index(AllowMultiple = true)].

TPH1004 — component declared twice in one inheritance chain

An archetype re-registers a component it already inherits, wasting a slot and a cluster column. Fix: remove the Register call.

TPH1101 — replicated type not partial

The replication generator implements members on [Replicated] / [ReplicatedMessage] types. Fix: add partial.

TPH1102 — more than one position

An archetype marks several Comp<T> fields [Motion] or [Position]. Fix: keep one.

TPH1104 — no default codec

The field's type has no exact wire form. Fix: name a codec, e.g. [Replicate(CodecKind.Quant, Min = …, Max = …, Bits = 24)].

TPH1105 — invalid [Fraction]

The [Fraction] attribute names a missing or incompatible maximum field. Fix: follow the message.

TPH1106 — misplaced replication attribute

A replication attribute sits where it has no effect. Fix: move or remove it.

TPH1107 — codec the field cannot carry

The chosen CodecKind does not fit the field's type. Fix: pick a codec for that type.

TPH1108 — both public and owner-only

A field is both [Replicate] (sent to every client) and [Owner]. Fix: drop one; a public [Fraction] beside a private [Owner] shows a coarse value to all and the exact one to its owner.

TPH1109 — unsupported replicated type

The type cannot be replicated. Fix: follow the message.