Entity Component System

Brine2D uses a hybrid ECS designed to be beginner-friendly with optional performance optimization. You don't need to learn systems or queries to get started — components and behaviors are enough for most games.

The Three Building Blocks

Concept	Purpose	Example
Component	Data container with lifecycle hooks	HealthComponent, TransformComponent
Behavior	Per-entity logic with DI support	PlayerMovementBehavior, EnemyAIBehavior
System	Batch processing for performance	MovementSystem, CollisionDetectionSystem

Quick Example

// 1. Component — data
public class HealthComponent : Component
{
    public int Current { get; set; } = 100;
    public int Max { get; set; } = 100;

    protected internal override void OnAdded() => Current = Max;
}

// 2. Behavior — per-entity logic
public class DamageFlashBehavior : Behavior
{
    protected override void Update(GameTime gameTime)
    {
        var health = Entity.GetComponent<HealthComponent>();
        if (health != null && health.Current < health.Max)
        {
            // Flash red when damaged
        }
    }
}

// 3. Use in a scene
protected override void OnEnter()
{
    var player = World.CreateEntity(""Player"");
    player.AddComponent<HealthComponent>();
    player.AddBehavior<DamageFlashBehavior>();
}

When to Use What

Scenario	Components	Behaviors	Systems
Data storage
Unique behavior (player, boss)
Simple games (< 500 entities)
Performance-critical (1000+ entities)

Rule of thumb: Start with components + behaviors, add systems only if profiling shows a need.

Scoped World

Each scene gets its own IEntityWorld. Entities are destroyed automatically when the scene unloads:

protected override void OnEnter()
{
    World.CreateEntity(""Player"");
    World.CreateEntity(""Enemy"");
    // Both destroyed automatically when scene unloads — no cleanup needed!
}

Learn More

For the complete ECS guide with detailed coverage of entities, components, behaviors, systems, and queries:

ECS — Full Guide

ECS Getting Started

Entities | Components | Systems | Queries