fledge_ecs library

A Bevy-inspired Entity Component System (ECS) for Dart and Flutter.

Fledge ECS provides a high-performance, type-safe ECS architecture with archetype-based storage and concurrent system execution.

Core Concepts

  • Entity: A unique identifier for a game object
  • Component: Pure data attached to entities
  • System: Logic that operates on entities with specific components
  • World: The container for all ECS data
  • Query: Type-safe iteration over entities with specific components

Example

// Define components
@component
class Position {
  double x, y;
  Position(this.x, this.y);
}

@component
class Velocity {
  double dx, dy;
  Velocity(this.dx, this.dy);
}

// Create world and spawn entities
final world = World();
world.spawn()
  ..insert(Position(0, 0))
  ..insert(Velocity(1, 1));

// Query and update
for (final (entity, pos, vel) in world.query2<Position, Velocity>().iter()) {
  pos.x += vel.dx;
  pos.y += vel.dy;
}

Classes

Added<T>
Filter for entities where component T was added recently.
And<T extends Record>
Combines multiple filters with AND logic.
App
The main application builder for ECS games.
AppRunner
Runner for apps with frame timing.
ArchetypeId
Identifies an archetype by its set of component types.
Archetypes
Manages all archetypes and their storage tables.
AsyncFunctionSystem
An async system created from a function.
BatchEntitySerializer
Serializes multiple entities.
Changed<T>
Filter for entities where component T was modified recently.
Children
Component that stores references to an entity's children.
Command
A deferred command to be executed on the world.
Commands
A buffer for deferred world mutations.
Component
Annotation class for component.
ComponentDescriptor<T>
Descriptor for a component type with its metadata.
ComponentId
A unique identifier for a component type.
ComponentTicks
Tracks when a component was added and last changed.
ComponentTypeInfo<T>
Runtime type information for a component.
CustomCommand
Command to run a custom function on the world.
DespawnCommand
Command to despawn an entity.
DespawnRecursiveCommand
Command to recursively despawn an entity and all its descendants.
Entities
Manages entity allocation, deallocation, and location tracking.
Entity
A unique identifier for an entity in the ECS world.
EntityCommands
Builder for spawning entities with components.
EntitySerializer
Serialization utilities for ECS data.
Event
Annotation class for event.
EventQueue<T>
Double-buffered event queue for a specific event type.
EventReader<T>
Read access to events of type T.
EventReadWriter<T>
Combined read and write access to events of type T.
Events
Container for all event queues.
EventWriter<T>
Write access to events of type T.
FieldInfo
Metadata about a field in a component.
FrameAware
Interface for resources that need per-frame lifecycle callbacks.
FrameLimiterConfig
Configuration for frame rate limiting.
FrameLimiterPlugin
Plugin that provides frame rate limiting.
FrameLimiterSystem
System that limits frame rate by sleeping.
FrameStartSystem
System that records frame start time.
FrameTime
Resource tracking frame timing.
FunctionPlugin
A simple plugin created from a function.
FunctionSystem
A system created from a function.
InsertCommand<T>
Command to insert a component into an entity.
InState<S extends Enum>
Run condition that returns true when in the specified state.
NoFilter
Marker for no filter.
Observer<T>
An observer that reacts to component lifecycle events.
Observers
Registry for managing component observers.
OnEnterState<S extends Enum>
Run condition that returns true when just entering the specified state.
OnExitState<S extends Enum>
Run condition that returns true when just exiting the specified state.
Option<T>
Marker type for optional component access in queries.
Parent
Component that stores a reference to an entity's parent.
Plugin
Base interface for plugins.
PluginGroup
A plugin that groups other plugins.
Query
A query for iterating over entities with specific components.
Query1<T1>
Query for a single component type.
Query2<T1, T2>
Query for two component types.
Query3<T1, T2, T3>
Query for three component types.
Query4<T1, T2, T3, T4>
Query for four component types.
QueryFilter
Base class for query filters.
QueryIter1<T1>
Iterator over query results for a single component.
QueryIter2<T1, T2>
Iterator over query results for two components.
QueryIter3<T1, T2, T3>
Iterator over query results for three components.
QueryIter4<T1, T2, T3, T4>
Iterator over query results for four components.
QueryState
Cached state for a query.
Reflectable
Annotation class for reflectable.
RemoveCommand<T>
Command to remove a component from an entity.
Res<T>
Read-only accessor for a resource.
ResMut<T>
Mutable accessor for a resource.
ResOption<T>
Optional resource accessor.
Resource
Annotation class for resource.
Resources
Container for global singleton resources.
RunConditions
Common run conditions for systems.
Schedule
The schedule containing all systems organized by stage.
SetConfiguredSystem
A system wrapper that applies set configuration.
SpawnChildCommand
Command to spawn a new entity as a child of a parent.
SpawnCommand
Command to spawn a new entity.
State<S extends Enum>
A state machine for tracking game/application state.
StateConditions
Helper class for creating state-related run conditions.
StateRegistry
Registry for managing multiple state machines by type.
SyncSystem
A synchronous system that doesn't need async operations.
System
Base interface for all systems.
SystemAnnotation
Annotation class for system.
SystemMeta
Describes the data access patterns of a system.
SystemNode
A node in the system dependency graph.
SystemSet
Configuration for a group of systems.
SystemSetRegistry
Registry for managing system sets.
SystemStage
A stage containing systems that run together.
Table
Dense storage for entities with the same archetype.
Tick
Global tick counter for change detection.
Time
Time resource providing delta time and elapsed time.
TimePlugin
Plugin that provides time tracking functionality.
TimeUpdateSystem
System that updates the Time resource each frame.
TypeRegistry
A registry for component type metadata.
With<T>
Filter that requires an entity to have component T.
Without<T>
Filter that requires an entity to NOT have component T.
World
The central container for all ECS data.

Enums

CoreStage
Core schedule stages for system execution ordering.
TriggerKind
The kind of trigger that activates an observer.

Mixins

ChangeTracking
Mixin for resources that need frame-level change tracking.

Extensions

TypeRegistryExtension on TypeRegistry
Extension to make registration more convenient.
WorldHierarchyExtension on World
Extension on World for managing entity hierarchies.
WorldSerializationExtension on World
Extension on World for serialization support.
WorldStateExtension on World
Extension on World for convenient state access.

Constants

component → const Component
Marks a class as an ECS component.
event → const Event
Marks a class as an event type.
reflectable → const Reflectable
Marks a component as reflectable for serialization and editor tooling.
resource → const Resource
Marks a class as a global resource.
system → const SystemAnnotation
Marks a function as an ECS system.

Typedefs

ObserverCallback<T> = void Function(World world, Entity entity, T component)
A callback type for observer reactions.
OptionalComponent<T> = T?
Type alias for clarity in query results. When a component is optional, it may be null.
RunCondition = bool Function(World world)
A condition that determines whether a system should run.