Home

What is ECS?

ECS (Event Component System) is a modular state management system for Flutter.
It provides a structured approach to separate data, behavior, and logic in your app.

The system is built around these core concepts:

• Entities – Objects or state holders in the system.
• Components – Data containers attached to entities.
• Systems – Logic units that process entities and components.
• Features – Groups of entities and systems to organize your app.
• Manager – The central coordinator that handles features, systems, and entities.

ECS supports:

• Reactive updates – Widgets automatically rebuild when entity state changes.
• Lifecycle management – Systems can initialize, execute, clean up, and teardown.
• UI integration – Widgets can access ECS state via ECSContext and ECSWidget.

Benefits of ECS in Flutter

1. Separation of Concerns

   • Data (Components) is separated from logic (Systems) and UI (Widgets).

2. Reactive Programming

   • Changes to entities automatically notify systems and UI components.

3. Modular Architecture

   • Features allow grouping related entities and systems for easier maintenance.

4. Global State Management

   • ECSManager provides a centralized way to access entities across the app.

5. Lifecycle Control

   • Systems can perform setup (InitializeSystem), periodic updates (ExecuteSystem), cleanup (CleanupSystem), and teardown (TeardownSystem).

Core Structure

• ECSManager: Root of the ECS system; coordinates features and entities.
• ECSFeature: Groups related entities and systems.
• ECSEntity / ECSComponent: Data objects that hold state.
• ECSSystem: Logic that processes entities or reacts to changes.
• ECSLogger: Provides logging and debugging support.

Recommended Usage

• Organize your app into features for logical separation.
• Use reactive systems for automatic reactions to entity changes.
• Wrap your widget tree with ECSScope for UI integration.
• Access entities in widgets using ECSContext.watch or ECSContext.get.