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 becomes DeltaTime × N. 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
Input(Func<ViewBase>)
Set the View factory providing the system's entity input.
public SystemBuilder Input(Func<ViewBase> viewFactory)Parameters
Returns
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[]) — all systems in phase N complete before any system in phase N+1 of the same DAG. 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
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
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 EntityRef.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