Class SystemBuilder
Configuration builder for class-based system definitions. Used by CallbackSystem, QuerySystem, and PipelineSystem in their Configure method.
public sealed class SystemBuilder- Inheritance
-
SystemBuilder
- Inherited Members
Remarks
All methods return the builder so calls can chain: b.Name("X").After("Y").Reads<Position>().Writes<Velocity>().
Constructors
SystemBuilder()
public SystemBuilder()Methods
AdditionalReads<T>()
Declare a read of T beyond the system's primary View input (cross-entity read).
public SystemBuilder AdditionalReads<T>() where T : unmanagedReturns
Type Parameters
T
After(string)
Declare a dependency on another system (this system runs after it).
public SystemBuilder After(string dependency)Parameters
dependencystring
Returns
AfterAll(params string[])
Declare dependencies on multiple systems (this system runs after all of them).
public SystemBuilder AfterAll(params string[] dependencies)Parameters
dependenciesstring[]
Returns
Before(string)
Declare that this system must run before another (mirror of After(string)). Useful for the W×W disambiguation case (RFC 07 / Q5).
public SystemBuilder Before(string dependent)Parameters
dependentstring
Returns
CanShed(bool)
Set whether this system can be shed entirely under severe overload.
public SystemBuilder CanShed(bool value)Parameters
valuebool
Returns
CellAmortize(int)
Set the cell-level amortization denominator (issue #231). When greater than 0, the system processes 1/N of the tier's clusters per tick,
and AmortizedDeltaTime carries the × N — together with the rate divisors, and only on the runs that actually strided
(DSEL-03). Requires a non-All Tier(SimTier).
public SystemBuilder CellAmortize(int denominator)Parameters
denominatorint
Returns
ChangeFilter(params Type[])
Set the component types for change-filtered reactive input. OR logic: entity included if any filtered component was written.
public SystemBuilder ChangeFilter(params Type[] componentTypes)Parameters
componentTypesType[]
Returns
Checkerboard()
Enable two-phase checkerboard dispatch (issue #234). Requires Parallel(). Clusters are split into Red/Black sets based on cell coordinates — no two adjacent cells are processed simultaneously.
public SystemBuilder Checkerboard()Returns
ChunkedParallel(int)
Enable chunk-parallel execution for a CallbackSystem with an explicit chunk count, independent of any entity input. The system's
Execute is invoked chunkCount times in parallel across workers; each invocation receives ChunkIndex
and ChunkCount so the implementation can offset its data accordingly.
Designed for non-entity-iterating work that's naturally chunkable — e.g. SIMD sweeps over flat arrays, image downsamples, parallel reductions. Skips all entity-prep infrastructure (Accessor, Entities, per-chunk Transaction): the TickContext passed in carries only tick metadata + ChunkIndex/ChunkCount.
Incompatible with Input(Func<ViewBase>), ChangeFilter(params Type[]), WritesVersioned(), Tier(SimTier), CellAmortize(int), Checkerboard(), and ChunksPerWorker(float) — all of those are entity-context concepts.
public SystemBuilder ChunkedParallel(int chunkCount)Parameters
chunkCountint
Returns
ChunksPerWorker(float)
Oversubscription factor for parallel chunk dispatch. The effective worker-cap on chunk count becomes
round(WorkerCount × factor) instead of WorkerCount. Default 1.0f.
Use values above 1.0 (e.g. 1.5, 2.0) when a parallel system shows poor worker efficiency because one slow chunk holds
back the critical path — extra chunks let fast workers steal more work via the dynamic dispatch loop. Final chunk count
is still capped by ceil(entityCount / ParallelQueryMinChunkSize), so small populations don't proliferate chunks.
[1.0, 64.0], and rejected on non-parallel systems where it has no effect.
public SystemBuilder ChunksPerWorker(float factor)Parameters
factorfloat
Returns
ExclusivePhase()
Mark this system as having exclusive control of its phase — no other system in the same phase may run concurrently. Use sparingly for systems that own the tick boundary (e.g. archetype cleanup, spatial-index update).
public SystemBuilder ExclusivePhase()Returns
InRealm(RealmId)
Narrows this QuerySystem to realm realm (Realms): it is dispatched that realm's clusters only — read from the realm's own cluster
list, not filtered out of every realm's — and a change filter sees that realm's changes only. A realm not runnable this tick (dormant) gives it
nothing, like any other system. See InRealms(params RealmId[]).
public SystemBuilder InRealm(RealmId realm)Parameters
realmRealmId
Returns
InRealms(params RealmId[])
Narrows this QuerySystem to the realms realms: their clusters only, and a change filter sees their changes only. A realm may be
registered after the runtime is built (it is dispatched from the tick it is registered); it must be below the engine's realm count.
public SystemBuilder InRealms(params RealmId[] realms)Parameters
realmsRealmId[]
Returns
Exceptions
- ArgumentException
No realm, or None.
Input(Func<ViewBase>)
Set the View factory providing the system's entity input.
public SystemBuilder Input(Func<ViewBase> viewFactory)Parameters
Returns
MinChunkSize(int)
Override ParallelQueryMinChunkSize for this system only — the smallest entity count
it will accept in a parallel chunk. Default 0 inherits the global value.
public SystemBuilder MinChunkSize(int entities)Parameters
entitiesint
Returns
Remarks
Set this when the system's cost PER ENTITY is far above the schedule's average, so that a chunk of the
global size is much more work than the dispatch it is sized against. The symptom is a system consuming a large
share of the tick while SystemTelemetry.WorkersTouched shows it running on a handful of workers, and
ChunksPerWorker(float) having no effect — because the entity-count cap, not the worker cap, is binding.
Validated at Build(IResource, ILogger): must be at least 1, and rejected on non-parallel systems where it has no effect.
Name(string)
Set the system's unique name in the DAG.
public SystemBuilder Name(string name)Parameters
namestring
Returns
Parallel()
Enable automatic chunk-parallel execution across workers. QuerySystem only.
public SystemBuilder Parallel()Returns
Phase(Phase)
Assign this system to a phase (RFC 07 / Q3). Phases form a DAG-local total order declared via Phases(params Phase[]), and it binds through declared access only: this system starts after a system of an earlier phase when their declarations conflict (rule ED-05), and may run alongside it otherwise — so declare every component it reads, including through spatial queries. The phase must be one declared on the owning DAG. If not called, the system lands in the DAG's default phase.
public SystemBuilder Phase(Phase phase)Parameters
phasePhase
Returns
Priority(SystemPriority)
Set the system's overload priority.
public SystemBuilder Priority(SystemPriority priority)Parameters
prioritySystemPriority
Returns
ReadsEvents(EventQueueBase)
Declare that this system consumes from the given event queue.
public SystemBuilder ReadsEvents(EventQueueBase queue)Parameters
queueEventQueueBase
Returns
ReadsFresh<T>()
Declare that this system reads component T and must be ordered AFTER any same-phase writer of T (sees this-tick value).
public SystemBuilder ReadsFresh<T>() where T : unmanagedReturns
Type Parameters
T
ReadsFresh<T1, T2>()
Batch form of ReadsFresh<T>(): declares fresh reads (each ordered after any same-phase writer) of all listed component types.
public SystemBuilder ReadsFresh<T1, T2>() where T1 : unmanaged where T2 : unmanagedReturns
Type Parameters
T1T2
ReadsFresh<T1, T2, T3>()
Batch form of ReadsFresh<T>(): declares fresh reads (each ordered after any same-phase writer) of all listed component types.
public SystemBuilder ReadsFresh<T1, T2, T3>() where T1 : unmanaged where T2 : unmanaged where T3 : unmanagedReturns
Type Parameters
T1T2T3
ReadsFresh<T1, T2, T3, T4>()
Batch form of ReadsFresh<T>(): declares fresh reads (each ordered after any same-phase writer) of all listed component types.
public SystemBuilder ReadsFresh<T1, T2, T3, T4>() where T1 : unmanaged where T2 : unmanaged where T3 : unmanaged where T4 : unmanagedReturns
Type Parameters
T1T2T3T4
ReadsFresh<T1, T2, T3, T4, T5>()
Batch form of ReadsFresh<T>(): declares fresh reads (each ordered after any same-phase writer) of all listed component types.
public SystemBuilder ReadsFresh<T1, T2, T3, T4, T5>() where T1 : unmanaged where T2 : unmanaged where T3 : unmanaged where T4 : unmanaged where T5 : unmanagedReturns
Type Parameters
T1T2T3T4T5
ReadsFresh<T1, T2, T3, T4, T5, T6>()
Batch form of ReadsFresh<T>(): declares fresh reads (each ordered after any same-phase writer) of all listed component types.
public SystemBuilder ReadsFresh<T1, T2, T3, T4, T5, T6>() where T1 : unmanaged where T2 : unmanaged where T3 : unmanaged where T4 : unmanaged where T5 : unmanaged where T6 : unmanagedReturns
Type Parameters
T1T2T3T4T5T6
ReadsResource(string)
Declare that this system reads a named resource.
public SystemBuilder ReadsResource(string name)Parameters
namestring
Returns
ReadsSnapshot<T>()
Declare that this system reads component T and must be ordered BEFORE any same-phase writer of T (sees previous-tick value, enables parallelism with the writer).
public SystemBuilder ReadsSnapshot<T>() where T : unmanagedReturns
Type Parameters
T
ReadsSnapshot<T1, T2>()
Batch form of ReadsSnapshot<T>(): declares snapshot reads (each ordered before any same-phase writer) of all listed component types.
public SystemBuilder ReadsSnapshot<T1, T2>() where T1 : unmanaged where T2 : unmanagedReturns
Type Parameters
T1T2
ReadsSnapshot<T1, T2, T3>()
Batch form of ReadsSnapshot<T>(): declares snapshot reads (each ordered before any same-phase writer) of all listed component types.
public SystemBuilder ReadsSnapshot<T1, T2, T3>() where T1 : unmanaged where T2 : unmanaged where T3 : unmanagedReturns
Type Parameters
T1T2T3
ReadsSnapshot<T1, T2, T3, T4>()
Batch form of ReadsSnapshot<T>(): declares snapshot reads (each ordered before any same-phase writer) of all listed component types.
public SystemBuilder ReadsSnapshot<T1, T2, T3, T4>() where T1 : unmanaged where T2 : unmanaged where T3 : unmanaged where T4 : unmanagedReturns
Type Parameters
T1T2T3T4
ReadsSnapshot<T1, T2, T3, T4, T5>()
Batch form of ReadsSnapshot<T>(): declares snapshot reads (each ordered before any same-phase writer) of all listed component types.
public SystemBuilder ReadsSnapshot<T1, T2, T3, T4, T5>() where T1 : unmanaged where T2 : unmanaged where T3 : unmanaged where T4 : unmanaged where T5 : unmanagedReturns
Type Parameters
T1T2T3T4T5
ReadsSnapshot<T1, T2, T3, T4, T5, T6>()
Batch form of ReadsSnapshot<T>(): declares snapshot reads (each ordered before any same-phase writer) of all listed component types.
public SystemBuilder ReadsSnapshot<T1, T2, T3, T4, T5, T6>() where T1 : unmanaged where T2 : unmanaged where T3 : unmanaged where T4 : unmanaged where T5 : unmanaged where T6 : unmanagedReturns
Type Parameters
T1T2T3T4T5T6
Reads<T>()
Declare that this system reads component T. Unit 3 errors at Build() if a same-phase writer of T exists — upgrade to ReadsFresh<T>() or ReadsSnapshot<T>().
public SystemBuilder Reads<T>() where T : unmanagedReturns
Type Parameters
T
Reads<T1, T2>()
Batch form of Reads<T>(): declares reads of all listed component types.
public SystemBuilder Reads<T1, T2>() where T1 : unmanaged where T2 : unmanagedReturns
Type Parameters
T1T2
Reads<T1, T2, T3>()
Batch form of Reads<T>(): declares reads of all listed component types.
public SystemBuilder Reads<T1, T2, T3>() where T1 : unmanaged where T2 : unmanaged where T3 : unmanagedReturns
Type Parameters
T1T2T3
Reads<T1, T2, T3, T4>()
Batch form of Reads<T>(): declares reads of all listed component types.
public SystemBuilder Reads<T1, T2, T3, T4>() where T1 : unmanaged where T2 : unmanaged where T3 : unmanaged where T4 : unmanagedReturns
Type Parameters
T1T2T3T4
Reads<T1, T2, T3, T4, T5>()
Batch form of Reads<T>(): declares reads of all listed component types.
public SystemBuilder Reads<T1, T2, T3, T4, T5>() where T1 : unmanaged where T2 : unmanaged where T3 : unmanaged where T4 : unmanaged where T5 : unmanagedReturns
Type Parameters
T1T2T3T4T5
Reads<T1, T2, T3, T4, T5, T6>()
Batch form of Reads<T>(): declares reads of all listed component types.
public SystemBuilder Reads<T1, T2, T3, T4, T5, T6>() where T1 : unmanaged where T2 : unmanaged where T3 : unmanaged where T4 : unmanaged where T5 : unmanaged where T6 : unmanagedReturns
Type Parameters
T1T2T3T4T5T6
RealmRate(RealmRate)
How this QuerySystem runs over realms simulated at a divisor (Realms D4): Divided (the default) visits each cluster of an N-divided realm once every N runs; Full visits every runnable cluster every run.
public SystemBuilder RealmRate(RealmRate rate)Parameters
rateRealmRate
Returns
ShouldRun(Func<bool>)
Set a predicate that must return true for the system to execute. Evaluated before any input processing.
public SystemBuilder ShouldRun(Func<bool> predicate)Parameters
Returns
SideWrites<T>()
Declare that this system writes T via a side-transaction (Immediate). Surfaced in tooling but does NOT affect scheduler ordering.
public SystemBuilder SideWrites<T>() where T : unmanagedReturns
Type Parameters
T
ThrottledTickDivisor(int)
Set the throttled tick divisor (system runs every Nth tick under overload).
public SystemBuilder ThrottledTickDivisor(int divisor)Parameters
divisorint
Returns
TickDivisor(int)
Set the tick divisor (system runs every Nth tick at normal load).
public SystemBuilder TickDivisor(int divisor)Parameters
divisorint
Returns
TickOffset(int)
Pins which of its divisor's ticks this system runs on, instead of letting the schedule stagger it.
public SystemBuilder TickOffset(int offset)Parameters
offsetintA tick phase below the tightest of this system's rate gates — its
TickDivisorand itsThrottledTickDivisor.
Returns
- SystemBuilder
This builder.
Remarks
Normally you do not set this. RuntimeSchedule.Build assigns an offset to every divided system so that the slow work in a schedule does
not all land on the same tick, and declaring a system should not require knowing what else is in the schedule.
The reason to set it is two INDEPENDENT systems that want the same tick because they share a cache-hot working set — the automatic assignment would spread them, having no way to know they are related. Systems the DAG already joins need no help: DSEL-04 gives a whole dependency closure one offset.
Refused at build when it is out of range for the system's gates, when its closure cannot all reach it, or when it disagrees with another explicit offset in the same closure.
Tier(SimTier)
Set the simulation-tier dispatch filter (issue #231). Default All matches pre-#231 behaviour (all clusters dispatched). Single-tier (e.g. Tier0) or multi-tier flag combinations (Near, Active) are both supported.
public SystemBuilder Tier(SimTier tier)Parameters
tierSimTier
Returns
WritesEvents(EventQueueBase)
Declare that this system publishes to the given event queue. Unit 3 derives a producer→consumer edge from this against any matching ReadsEvents(EventQueueBase) in the same phase.
public SystemBuilder WritesEvents(EventQueueBase queue)Parameters
queueEventQueueBase
Returns
WritesResource(string)
Declare that this system mutates a named resource (e.g., a shared physics-world handle that isn't a component).
public SystemBuilder WritesResource(string name)Parameters
namestring
Returns
WritesVersioned()
Declare that this parallel QuerySystem writes Versioned components. Forces per-chunk Transaction fallback instead of the optimized PointInTimeAccessor path.
public SystemBuilder WritesVersioned()Returns
Writes<T>()
Declare that this system mutates component T via EntityRefMut.Write<T>(). Unit 3 errors at Build() if another system in the same phase also declares Writes<T> without an explicit After(string)/Before(string).
public SystemBuilder Writes<T>() where T : unmanagedReturns
Type Parameters
T
Writes<T1, T2>()
Batch form of Writes<T>(): declares writes of all listed component types.
public SystemBuilder Writes<T1, T2>() where T1 : unmanaged where T2 : unmanagedReturns
Type Parameters
T1T2
Writes<T1, T2, T3>()
Batch form of Writes<T>(): declares writes of all listed component types.
public SystemBuilder Writes<T1, T2, T3>() where T1 : unmanaged where T2 : unmanaged where T3 : unmanagedReturns
Type Parameters
T1T2T3
Writes<T1, T2, T3, T4>()
Batch form of Writes<T>(): declares writes of all listed component types.
public SystemBuilder Writes<T1, T2, T3, T4>() where T1 : unmanaged where T2 : unmanaged where T3 : unmanaged where T4 : unmanagedReturns
Type Parameters
T1T2T3T4
Writes<T1, T2, T3, T4, T5>()
Batch form of Writes<T>(): declares writes of all listed component types.
public SystemBuilder Writes<T1, T2, T3, T4, T5>() where T1 : unmanaged where T2 : unmanaged where T3 : unmanaged where T4 : unmanaged where T5 : unmanagedReturns
Type Parameters
T1T2T3T4T5
Writes<T1, T2, T3, T4, T5, T6>()
Batch form of Writes<T>(): declares writes of all listed component types.
public SystemBuilder Writes<T1, T2, T3, T4, T5, T6>() where T1 : unmanaged where T2 : unmanaged where T3 : unmanaged where T4 : unmanaged where T5 : unmanaged where T6 : unmanagedReturns
Type Parameters
T1T2T3T4T5T6