Skip to content

Scope

Jump to bottom
Ehsan Rashidi edited this page Oct 27, 2025 · 1 revision

Scope

Overview

ECSScope is a Flutter widget that manages a set of ECS features within a widget tree. It serves as a bridge between the ECS architecture and Flutter's UI, enabling features to be initialized, executed, cleaned up, and torn down in sync with the widget lifecycle.

Key Responsibilities

  • Feature Management: ECSScope adds provided features to an ECSManager and activates them. When the scope is removed, features are automatically deactivated and removed from the manager.
  • Lifecycle Handling: It ensures that initialize systems run after the first frame, execute and cleanup systems are periodically updated using a ticker, and teardown systems are executed when the scope is disposed.
  • Nested Scopes: Developers can nest multiple ECSScope widgets. Features contained in nested scopes are automatically added to and removed from the ECS setup, allowing modular feature management.
  • Primary Scope: The first scope in the widget tree becomes the primary ECS scope, which is responsible for driving the periodic execution loop for execute and cleanup systems.
  • DevTools Integration: Registers a DevTools extension to allow inspection of ECS manager data, enabling debugging and monitoring of features and entities.

Interaction with ECS Manager

ECSScope interacts closely with the ECSManager, ensuring that features are properly registered, activated, and removed. This provides a seamless integration of ECS entities and systems within the Flutter app.

Lifecycle Events

  • Initialization: Features are initialized after the widget is inserted into the tree.
  • Execution: Execute and cleanup systems are triggered on each frame using a ticker for timing.
  • Deactivation: When the widget is removed from the tree, features are deactivated and teardown systems run.
  • Nested Handling: Nested scopes automatically register and unregister their features in the manager.

By using ECSScope, developers can manage ECS features in a structured and Flutter-friendly way, while maintaining a clean separation between business logic and UI.

Clone this wiki locally