Strada Framework

A high-performance Unity framework unifying Patterns architecture with ECS simulation

Language: English | 日本語 | 简体中文 | 繁體中文 | 한국어

Strada combines enterprise-grade dependency injection with performance-critical ECS, wrapped in a clean modular architecture. Build UI with familiar patterns while using ECS for high-performance simulation—without choosing between paradigms.

---

Table of Contents

• Features
• Installation
• Quick Start
• Performance
• Documentation
• Architecture
• API Reference
• Testing
• License

---

Features

Dependency Injection (docs)

• Container: Expression tree compiled factories (1.56x manual new() overhead)
• Lifetimes: Singleton, Transient, Scoped with thread-safe initialization
• Disposal: LIFO disposal order (dependents disposed before dependencies)
• Auto-Binding: Attribute-based service registration with [AutoRegister], [AutoRegisterSingleton], etc.
• Circular Detection: Build-time cycle detection prevents runtime errors
• Zero-alloc Resolution: No GC allocation for singleton/scoped paths
• Thread-Safe: Volatile reads, ConcurrentDictionary, and lock-based disposal safety

Entity Component System (docs)

• SparseSet Storage: Cache-friendly component iteration (6-28ns per entity)
• Query System: ForEach<T1...T16>() - up to 8 hand-written, 9-16 source-generated
• Safety: EntityCommandBuffer for safe structural changes during iteration
• Parallel Jobs: Burst-compiled jobs with 17x speedup over sequential
• Entity Recycling: Automatic index reuse with version tracking
• Source Generation: Compile-time query generation for 9-16 components

Messaging (docs)

• MessageBus: Unified command/query/event bus with array-indexed dispatch (4ns/dispatch)
• Pooled Commands: Execute ICommand objects with automatic pool return
• Zero-alloc Publish: Struct-based messages, no boxing
• Exception Isolation: Handler failures don't interrupt other subscribers

Patterns-ECS Sync (docs)

• Event-Driven Integration: ECS systems publish ComponentChanged events, Patterns controllers subscribe
• EntityMediator: Binds ECS entities to UI views with auto-sync and MessageBus integration
• Bidirectional Flow: Controllers send commands to ECS via MessageBus, receive events back

Reactive Bindings (docs)

• ReactiveProperty: Observable values with change notification
• ReactiveCollection: Observable lists with add/remove/clear events
• ComputedProperty: Derived values with automatic dependency tracking

Modular Architecture (docs)

• ModuleConfig: ScriptableObject-based module configuration
• Inspector Systems: Configure ECS systems via drag-and-drop
• IModuleBuilder: VContainer-like fluent API for DI registration
• System Discovery: Auto-find systems with [StradaSystem] attribute
• Priority Ordering: Control module initialization order

Utilities

• ObjectPool: Generic pooling with lifecycle hooks (Spawn/Despawn)
• StateMachine: Type-safe FSM with conditional transitions
• TimerService: Managed timers with pause/resume support

---

Installation

Add to your Unity project's Packages/manifest.json:

{
  "dependencies": {
    "com.strada.core": "file:../Packages/com.strada.core"
  }
}

Or copy the Packages/com.strada.core folder directly into your project.

Requirements:

• Unity 6000.0+ (Unity 6)
• .NET Standard 2.1

---

Quick Start

Dependency Injection

using Strada.Core.DI;
using Strada.Core.DI.Attributes;

// Option 1: Manual registration
var builder = new ContainerBuilder();
builder.Register<IPlayerService, PlayerService>(Lifetime.Singleton);
builder.Register<IInputService, InputService>(Lifetime.Singleton);
using var container = builder.Build();

// Option 2: Auto-binding with attributes
[AutoRegisterSingleton(As = typeof(IPlayerService))]
public class PlayerService : IPlayerService { }

[AutoRegisterTransient]
public class EnemyController { }

// Auto-register all attributed types
var builder = new ContainerBuilder();
builder.RegisterAutoBindings();  // Scans for [AutoRegister*] attributes
using var container = builder.Build();

ECS System

using Strada.Core.ECS;
using Strada.Core.ECS.Query;

// Define components (must be unmanaged structs)
public struct Position : IComponent { public float X, Y, Z; }
public struct Velocity : IComponent { public float X, Y, Z; }
public struct Health : IComponent { public int Current, Max; }
public struct Damage : IComponent { public int Value; }

// Query up to 8 components (hand-written, optimal performance)
entityManager.ForEach<Position, Velocity, Health, Damage>(
    (int entity, ref Position pos, ref Velocity vel, ref Health hp, ref Damage dmg) =>
    {
        pos.X += vel.X * deltaTime;
    });

// Query 9-16 components (source-generated)
entityManager.ForEach<T1, T2, T3, T4, T5, T6, T7, T8, T9>(...);

// Or use SystemBase for cleaner code
public class MovementSystem : SystemBase<Position, Velocity>
{
    protected override void OnUpdateEntity(int entity, ref Position pos, ref Velocity vel, float dt)
    {
        pos.X += vel.X * dt;
        pos.Y += vel.Y * dt;
        pos.Z += vel.Z * dt;
    }
}

Messaging

using Strada.Core.Communication;

// Define messages as structs
public struct PlayerDamaged { public int EntityId; public int Damage; }
public struct SpawnEnemy { public float X, Y; }

// Setup bus
var bus = new MessageBus();

// Subscribe to events
bus.Subscribe<PlayerDamaged>(e => Debug.Log($"Player took {e.Damage} damage"));

// Publish events (zero allocation)
bus.Publish(new PlayerDamaged { EntityId = 1, Damage = 10 });

// Register command handlers
bus.RegisterCommandHandler<SpawnEnemy>(cmd => SpawnEnemyAt(cmd.X, cmd.Y));
bus.Send(new SpawnEnemy { X = 10, Y = 20 });

Reactive Properties

using Strada.Core.Sync;

// Create reactive property
var health = new ReactiveProperty<int>(100);

// Subscribe to changes
health.Subscribe(value => healthBar.SetValue(value));

// Changes automatically notify subscribers
health.Value = 75; // healthBar updates automatically

---

Performance

Honest benchmarks measured on Apple Silicon (Unity 6, Mono):

DI Container

| Operation | Time | Notes | |-----------|------|-------| | Simple Transient | 0.11μs | Single class, no dependencies | | 4-Level Deep Chain | 0.27μs | A→B→C→D dependency chain | | Wide Service (5 deps) | 0.42μs | Class with 5 injected dependencies | | Singleton Lookup | 61ns | Already-created singleton | | Scoped Lookup | 21ns | Within existing scope | | Container Build (100 types) | 0.05ms | ~0.5μs per registration | | vs Manual new() | 1.56x | Competitive with best Unity DI |

ECS

| Operation | Time | Notes | |-----------|------|-------| | Entity Creation | 54ns | Bare entity | | Entity + 3 Components | 374ns | Full entity setup | | Single Component Query | 6.6ns/entity | 100k entities | | Two Component Query | 18ns/entity | 100k entities | | Three Component Query | 28ns/entity | 100k entities | | GetComponent | 67ns | Random access | | Simulation (100k, 10 frames) | 1.62ms/frame | Position += Velocity | | Parallel Job Speedup | 17x | vs sequential ForEach |

Memory

| Metric | Value | |--------|-------| | Memory per Entity (2 components) | 56 bytes | | GC Allocation (Singleton resolve) | 0 bytes | | GC Allocation (Scoped resolve) | 0 bytes |

Comparison

| Framework | Resolution Speed | vs Manual | |-----------|------------------|-----------| | Strada | 0.11-0.27μs | 1.56x | | VContainer | ~0.2-0.3μs | ~2x | | Reflex | ~0.5-1.0μs | ~3-5x | | Zenject | ~2-5μs | ~20-50x |

---

Documentation

| Document | Description | |----------|-------------| | Modules | Modular architecture, ModuleConfig, Inspector-configurable systems | | DI Container | Dependency injection, lifetimes, scopes | | ECS System | Entities, components, queries, systems | | Messaging | MessageBus, commands, events, queries | | Sync | Reactive properties, bindings, EntityMediator | | Pooling | Object pools, lifecycle hooks | | StateMachine | FSM with transitions | | TimerService | Managed timers with pause/resume | | Debugging | Troubleshooting, common issues, debugging tools | | Benchmarks | Full performance data |

---

Architecture

System Overview

┌─────────────────────────────────────────────────────────────────────────┐
│                          STRADA FRAMEWORK                                │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│   ┌─────────────────────────┐     ┌─────────────────────────┐          │
│   │    PATTERNS LAYER       │     │      ECS LAYER          │          │
│   │                         │     │                         │          │
│   │  ┌─────────────────┐    │     │  ┌─────────────────┐    │          │
│   │  │     Views       │