World class

A Bevy-inspired Entity-Component-System container backed by DIRegistry.

Components, resources, entity-presence markers, and bundles all live as dependencies in an internal DIRegistry; queries use its reverse type index to fetch matching entities in O(K) rather than scanning every dependency. The DI registry is exposed via registry so existing DI tooling (lifecycle callbacks, snapshots, change listeners) keeps working.

final world = World()
  ..insertResource(const GameTime(0))
  ..addStartupSystem(SpawnPlayer())
  ..addSystem(MovementSystem())
  ..addSystem(DamageSystem());

while (running) {
  world.update(const Duration(milliseconds: 16));
}

Constructors

World({Option<DIRegistry> registry = const None()})

Properties

elapsed → Duration
Cumulative time advanced through update since this world was created.
no setter
entities → Iterable<WorldEntity>
All entities currently alive in this world.
no setter
entityCount → int
Number of live entities.
no setter
hashCode → int
The hash code for this object.
no setterinherited
isDisposed → bool
Whether dispose has been called.
no setter
registry → DIRegistry
The backing DI registry. Components are stored under their owning entity's group; resources live under _resourceGroup; the alive-tag component anchors empty entities. Direct manipulation is supported but rarely needed — prefer the typed World / WorldEntity API.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
startupSystems → List<System>
Systems registered to run once before the first update.
no setter
systems → List<System>
Systems registered to run every update, in execution order.
no setter

Methods

addPlugin(EcsPlugin plugin) → World
Installs plugin, letting it register systems, resources, and event subscriptions. Returns this for chaining. Bevy's app.add_plugin(...).
addStartupSystem(System system) → World
Adds system to the startup schedule. Runs once, before the first regular update. Returns this for chaining.
addSystem(System system) → World
Adds system to the schedule. Runs every update in registration order. Returns this for chaining.
clearEntities() → void
Removes every entity and component but keeps systems, resources, and event subscriptions.
despawn(WorldEntity entity) → bool
Removes entity and all of its components. Returns true if the entity was alive.
dispose() → void
Tears the world down: disposes every system (startup and regular), cascades dispose() to every component / resource that mixes ServiceMixin, clears the registry, drops event subscriptions, and marks the world so further update calls are no-ops.
each1<T1 extends Component>() → Iterable<(WorldEntity, T1)>
Iterates (entity, T1) for every entity with a T1 component. Inspired by Bevy's Query<&T>.
each2<T1 extends Component, T2 extends Component>() → Iterable<(WorldEntity, T1, T2)>
Iterates (entity, T1, T2) for every entity with both components.
each3<T1 extends Component, T2 extends Component, T3 extends Component>() → Iterable<(WorldEntity, T1, T2, T3)>
Iterates (entity, T1, T2, T3) for every entity with all three.
get<T extends Component>(WorldEntity entity) → Option<T>
Reads the component of type T from entity, or None if absent.
getResource<T extends Resource>() → Option<T>
Returns the resource of type T, or None if not registered.
has<T extends Component>(WorldEntity entity) → bool
Whether entity has a component of type T.
insertResource<T extends Resource>(T resource) → void
Inserts or replaces the global resource of type T. Bevy's app.insert_resource(...).
mutate<T extends Component>(WorldEntity entity, T update(T current)) → Option<T>
Replaces the component of type T using update. Returns the new value, or None if entity has no component of type T.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
onEvent<E extends Event>(void listener(E event)) → void Function()
Subscribes to events of type E. The returned closure removes the subscription when called. Subtype propagation: a derived event sent via sendEvent is delivered to base-typed listeners as well.
query1<T1 extends Component>() → Iterable<WorldEntity>
query2<T1 extends Component, T2 extends Component>() → Iterable<WorldEntity>
query3<T1 extends Component, T2 extends Component, T3 extends Component>() → Iterable<WorldEntity>
query4<T1 extends Component, T2 extends Component, T3 extends Component, T4 extends Component>() → Iterable<WorldEntity>
query5<T1 extends Component, T2 extends Component, T3 extends Component, T4 extends Component, T5 extends Component>() → Iterable<WorldEntity>
queryTypes(List<Type> types) → Iterable<WorldEntity>
Entities that hold every type in types. The smallest matching bucket is iterated first; missing types short-circuit to an empty result.
readEvents<E extends Event>() → Iterable<E>
Returns the events of type E sent so far this (outer) tick. Filters the flat buffer by is E, so derived events are visible via base-typed readers and vice-versa is correctly excluded.
remove<T extends Component>(WorldEntity entity) → Option<T>
Removes the component of type T from entity.
removeResource<T extends Resource>() → Option<T>
Removes and returns the resource of type T.
removeSystem(System system) → bool
Removes system from either schedule, calling its System.dispose.
requireResource<T extends Resource>() → T
Returns the resource of type T or throws if not registered.
sendEvent<E extends Event>(E event) → void
Synchronously dispatches event to every listener whose registered type E is a supertype of event (subtype propagation — Liskov for events), then buffers it for readEvents until the next outer tick ends. A snapshot of the listener list is taken so subscribing or unsubscribing inside a handler does not affect the current dispatch.
set(WorldEntity entity, Component component) → void
Sets or replaces a component on entity.
spawn([Option<Iterable<Component>> components = const None()]) → WorldEntity
Spawns a new entity. If components are provided, they are attached immediately. Otherwise an alive-tag component is inserted so the entity remains visible to entities / queries until it gets real components.
spawnBundle(Bundle bundle) → WorldEntity
Spawns and returns the entity wrapped by bundle.
toString() → String
A string representation of this object.
inherited
update(Duration dt) → void
Advances the world by dt. The first call also runs every startup system. Drains the per-tick event buffer after all systems have run. No-op if the world has been disposed.
withComponent<T extends Component>() → Iterable<WorldEntity>
Every alive entity that has a component of type T. O(K) using the reverse type index in DIRegistry. A snapshot of the bucket is taken up-front so callers can safely insert, remove, or despawn entities mid-iteration.

Operators

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