LeoEcsLite Documentation

Before using LeoEcsLite, be aware of the following critical constraints:

• Maintenance Status: Support for this project has ended. It is in a stable state with no known bugs, but it is recommended to use EcsProto instead.
• Build Configurations: Use DEBUG builds during development to enable internal checks and exceptions. Use RELEASE builds for production to remove these checks for maximum performance.
• Thread Safety: LeoEcsLite is not thread-safe. If you require multi-threading, you must implement it yourself and integrate synchronization via an ECS system.
• Official Sources: The only official working version is at https://github.com/Leopotam/ecslite. Other sources like NuGet or NPM are unofficial clones and should be used at your own risk.

A Component is a container for user data. It should ideally be a struct and should not contain main logic (though minimal helpers are allowed). Components are managed through EcsPool.

struct Component1 {
    public int Id;
    public string Name;
}

An Entity is a container for components. It does not exist independently and is implemented simply as an int.

Key behaviors:

• Creation: Use world.NewEntity() to create a new entity.
• Deletion: Use world.DelEntity(entity) to destroy an entity. All components attached to it are automatically removed first.
• Copying: Use world.CopyEntity(srcEntity, dstEntity) to copy all components from one entity to another.
• Lifecycle: Entities cannot exist without components; an entity is automatically destroyed if its last component is removed.

// Create a new entity in the world.
int entity = _world.NewEntity ();

// Delete an entity (components are removed automatically first).
world.DelEntity (entity);

// Copy components from one entity to another.
world.CopyEntity (srcEntity, dstEntity);

An EcsWorld instance acts as the primary container for all entities, component pools, and filters. Data within an EcsWorld is unique and isolated from other worlds.

Lifecycle Management:

• You must call EcsWorld.Destroy() when the world is no longer needed to prevent memory leaks.

The EcsSystems class manages a collection of systems that process the EcsWorld. It provides a structured way to initialize and execute the logic loop.

Workflow:

1. Create an EcsSystems instance passing in an EcsWorld.
2. Use .Add(system) to register your systems.
3. Call .Init() to initialize all registered systems.
4. Call .Run() within your engine's main update loop to execute the systems.
5. Call .Destroy() when finished to clean up the systems.

Lifecycle Management:

• You must call IEcsSystems.Destroy() when the system group is no longer needed.

_world = new EcsWorld();
_systems = new EcsSystems(_world);
_systems
    .Add(new WeaponSystem())
    .Init();

// In update loop:
_systems.Run();

// Cleanup:
_systems.Destroy();
_world.Destroy();

You can provide a custom class instance (shared data) to all systems by passing it to the EcsSystems constructor. Systems can then retrieve this data using systems.GetShared<T>().

class SharedData {
    public string PrefabsPath;
}

// Setup
SharedData sharedData = new SharedData { PrefabsPath = "Items/{0}" };
IEcsSystems systems = new EcsSystems (world, sharedData);
systems.Add (new TestSystem1 ()).Init ();

// Usage in a system
class TestSystem1 : IEcsInitSystem {
    public void Init(IEcsSystems systems) {
        SharedData shared = systems.GetShared<SharedData> (); 
        string prefabPath = string.Format(shared.PrefabsPath, 123);
        // prefabPath = "Items/123"
    }
}

To use LeoECS Lite in a custom C# engine, ensure you are using C# 7.3 or higher. You need to manually manage the lifecycle of the EcsWorld and EcsSystems within your engine's execution flow.

using Leopotam.EcsLite;

class EcsStartup {
    EcsWorld _world;
    IEcsSystems _systems;

    void Init () {
        _world = new EcsWorld ();
        _systems = new EcsSystems (_world);
        _systems
            // .AddWorld (customWorldInstance, "events") // Optional: Register additional worlds
            .Add (new TestSystem1 ())
            .Init ();
    }

    void UpdateLoop () {
        _systems?.Run ();
    }

    void Destroy () {
        if (_systems != null) {
            _systems.Destroy ();
            _systems = null;
        }
        if (_world != null) {
            _world.Destroy ();
            _world = null;
        }
    }
}

Since entities are simple int types, you cannot safely store them directly in components if you need to verify if they still exist. Instead, wrap them in EcsPackedEntity or EcsPackedEntityWithWorld. When unpacking, these containers allow you to check if the entity is still valid.

EcsWorld world = new EcsWorld ();
int entity = world.NewEntity ();
EcsPackedEntity packed = world.PackEntity (entity);
EcsPackedEntityWithWorld packedWithWorld = world.PackEntityWithWorld (entity);

// Unpacking with EcsPackedEntity
if (packed.Unpack (world, out int unpacked)) {
    // "unpacked" is a valid entity
}

// Unpacking with EcsPackedEntityWithWorld
if (packedWithWorld.Unpack (out EcsWorld unpackedWorld, out int unpackedWithWorld)) {
    // "unpackedWithWorld" is a valid entity
}

To execute different sets of systems in Unity's Update and FixedUpdate methods, you must create separate IEcsSystems groups for each lifecycle method. Each group should be initialized with the same EcsWorld instance.

IEcsSystems _update;
IEcsSystems _fixedUpdate;

void Start () {
    EcsWorld world = new EcsWorld ();
    _update = new EcsSystems (world);
    _update
        .Add (new UpdateSystem ())
        .Init ();
    _fixedUpdate = new EcsSystems (world);
    _fixedUpdate
        .Add (new FixedUpdateSystem ())
        .Init ();
}

void Update () {
    _update?.Run ();
}

void FixedUpdate () {
    _fixedUpdate?.Run ();
}