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
Twas 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
Twas 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.