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 withextensionsinstalled, 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.
activeEntitiescounts the entities active in the hierarchy;lastUpdateMsandsystemTimesMs(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'sadopt, 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
-
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 unlessincludeInactive. -
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
withChildrenis 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 unlessincludeInactive. -
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
prefabblueprint. -
isEntityAlive(
Entity entity) → bool -
Whether
entityis this world's live entity for its id. -
markStructureChanged(
) → void -
Moves structureVersion on, for a change the world cannot see: a
ChildrenComponent'schildIdsreordered 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
componentTypesmatch 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