World class

ECS World - Manages all entities and systems

The central manager for the Entity-Component System. Entities are stored in Archetype tables grouped by component signature, giving systems cache-friendly iteration over matching entities.

Entity ids count up for the life of the world and are never reused, so state a system keeps by id cannot attach itself to a newer entity.

Every world reads its components, loaders and hooks from a context. The engine's world is given engine.context; so should any other world that works with the engine's scenes (the interface's screens, an editor's preview). World() with no context makes a fresh one — with the ECS core's own components, and extensions installed — and disposes it with the world. A world that reads or writes scenes needs the engine's features too: World(extensions: [BuiltInComponents.extension]).

Available extensions

Constructors

World({EngineContext? context, Iterable<ContextExtension> extensions = const []})
A world reading from context; when null, a fresh EngineContext with extensions installed, owned by this world.

Properties

activeEntities → Iterable<Entity>
The entities active in the hierarchy (Entity.isActiveInHierarchy), oldest first.
no setter
clearCount → int
How many times this world has been cleared (destroyAllEntities) — for a system that keeps state about the scene as a whole (a camera's last shot) to tell that a new one began.
no setter
commands → CommandBuffer
Deferred command buffer for safe structural mutations during iteration.
latefinal
context → EngineContext
Where this world's component definitions, loaders and hooks come from. Systems read it (world.context) rather than anything process-wide.
final
entities → UnmodifiableListView<Entity>
Every entity, oldest first.
no setter
entityCount → int
How many entities the world holds, switched off or not.
no setter
events → EventBus
Event bus for decoupled inter-system communication.
final
hashCode → int
The hash code for this object.
no setterinherited
profiling ↔ bool
Whether update times each system and itself for stats (systemTimesMs, lastUpdateMs).
getter/setter pair
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
stats → Map<String, dynamic>
Statistics, made when read. activeEntities counts the entities active in the hierarchy; lastUpdateMs and systemTimesMs (each system's last update, by System.profileName) are measured only while profiling is on.
no setter
structureVersion → int
A number that moves on whenever the world's shape may have changed, and never otherwise: an entity made or destroyed (one at a time, or all at once), a component added, removed or replaced, an entity switched on or off (Entity.isActive, its own flag or through a parent), or re-parented — through its ParentComponent, or settled by transformHierarchy's adopt, which is how an editor moves an entity to another parent or another place among its siblings. A change to a component's fields leaves it alone.
no setter
systems → UnmodifiableListView<System>
Every system, in the order they run. A snapshot: adding or removing systems while walking it is safe.
no setter
tagsInUse → Set<String>
Every tag some entity in this world carries.
no setter
transformHierarchy → TransformHierarchy
Keeps children's world transforms in step with their parents'.
latefinal
updateCount → int
How many times update has run. A renderer drawing between fixed updates compares it with the value it last saw to know whether one happened since its last frame.
no setter

Methods

addSystem(System system) → void
Add a system to the world.
allTagged(String tag, {bool includeInactive = false}) → List<Entity>
Every entity tagged tag, oldest first. Entities not active in the hierarchy (Entity.isActiveInHierarchy) are left out unless includeInactive.
clearSystems() → void
Remove all systems from the world.
createEntity({String? name}) → Entity
Create a new entity
createEntityWithComponents(List<Component> components, {String? name}) → Entity
Create an entity with components (batch — avoids per-component archetype migrations).
destroyAllEntities() → void
Destroy all entities
destroyEntity(Entity entity, {bool withChildren = true}) → void
Destroy an entity, and — unless withChildren is false — everything under it.
dispose() → void
Dispose the world and all systems
findEntityByName(String name, {bool includeInactive = true}) → Entity?
The oldest entity named name, or null.
findTagged(String tag, {bool includeInactive = false}) → Entity?
The oldest entity tagged tag, or null. Entities not active in the hierarchy (Entity.isActiveInHierarchy) are passed over unless includeInactive.
frame(double deltaTime, double alpha) → void
Runs every active PerFrame, in priority order: once per rendered frame, after its fixed updates (see PerFrame.frame).
getEntity(EntityId id) → Entity?
Get entity by ID (O(1) lookup).
getSystem<T extends System>() → T?
Get a system by type
hasSystem<T extends System>() → bool
Whether a system of type T (or a subtype) is in this world.
initialize() → void
Initialize the world: every system in it is initialized (System.initialize), in the order they run. One added afterwards is initialized as it is added — also one added by another system's initialize.
instantiate(EntityPrefab prefab) → Entity
Create a new entity from a prefab blueprint.
isEntityAlive(Entity entity) → bool
Whether entity is this world's live entity for its id.
markStructureChanged() → void
Moves structureVersion on, for a change the world cannot see: a ChildrenComponent's childIds reordered in place.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
query(List<Type> componentTypes) → List<Entity>
Find the entities active in the hierarchy (Entity.isActiveInHierarchy) that have every one of componentTypes. An entity switched off, or under a parent that is, is left out.
queryArchetypes(List<Type> componentTypes) → Iterable<Archetype>
Return all Archetypes whose component set is a superset of componentTypes.
queryVersion(List<Type> componentTypes) → int
A number that moves on whenever the entities componentTypes match may have changed — for a system that keeps something per matching entity (a draw list, physics bodies, a cache of components) and rebuilds it only when its own queries changed.
removeSystem(System system) → void
Remove a system from the world: it hears System.onRemovedFromWorld, then System.dispose.
render(Canvas canvas, Size size) → void
Render all active systems
sortSystems() → void
Puts the systems in priority order again — those of the same priority in the order they were added. They are placed as each is added; a System.priority that changed since — edited code after a hot reload — takes effect only once this runs. Systems already running this update keep the order they started in.
toSignal({String? debugLabel}) → WorldSignal

Available on World, provided by the WorldReactive extension

Creates a reactive signal wrapper for this world.
toString() → String
A string representation of this object.
inherited
update(double deltaTime) → void
Update all active systems, in order (see addSystem).

Operators

operator ==(Object other) → bool
The equality operator.
inherited