pico_ecs.h

Go to the documentation of this file.

 
#ifndef PICO_ECS_H
#define PICO_ECS_H
 
#include <stdbool.h> // bool, true, false
#include <stddef.h>  // size_t
#include <stdint.h>  // uint32_t, uint64_t
#include <limits.h>  // SIZE_MAX
 
#ifdef __cplusplus
extern "C" {
#endif
 
typedef struct ecs_s ecs_t;
 
#ifndef ECS_ID_TYPE
#define ECS_ID_TYPE uint64_t
#endif
 
typedef ECS_ID_TYPE ecs_id_t;
 
#ifndef ECS_MASK_TYPE
#define ECS_MASK_TYPE uint64_t
#endif
 
typedef ECS_MASK_TYPE ecs_mask_t;
 
typedef int32_t ecs_ret_t;
 
typedef struct ecs_entity_t { ecs_id_t id; } ecs_entity_t;
 
typedef struct ecs_comp_t { ecs_id_t id; } ecs_comp_t;
 
typedef struct ecs_system_t { ecs_id_t id; } ecs_system_t;
 
#define ECS_INVALID_ID ((ecs_id_t)-1)
 
#define ECS_IS_INVALID(obj) ((obj.id) == ECS_INVALID_ID)
 
ecs_t* ecs_new(size_t entity_capacity, void* mem_ctx);
 
void ecs_free(ecs_t* ecs);
 
void ecs_reset(ecs_t* ecs);
 
typedef void (*ecs_on_add_fn)(ecs_t* ecs,
                              ecs_entity_t entity,
                              ecs_comp_t comp,
                              const void* args,
                              void* udata);
 
typedef void (*ecs_on_remove_fn)(ecs_t* ecs,
                                 ecs_entity_t entity,
                                 ecs_comp_t comp,
                                 void* udata);
 
 
typedef void (*ecs_on_set_fn)(ecs_t* ecs,
                              ecs_entity_t entity,
                              ecs_comp_t comp,
                              void* udata);
 
typedef struct
{
    ecs_on_add_fn on_add_cb;
    ecs_on_remove_fn on_remove_cb;
    ecs_on_set_fn on_set_cb;
    void* default_value;
    size_t args_size;
    void* udata;
} ecs_comp_desc_t;
 
ecs_comp_t ecs_define_component(ecs_t* ecs,
                                size_t size,
                                const ecs_comp_desc_t* desc);
 
typedef ecs_ret_t (*ecs_system_fn)(ecs_t* ecs,
                                   ecs_entity_t* entities,
                                   size_t entity_count,
                                   void* udata);
 
typedef void (*ecs_on_join_fn)(ecs_t* ecs, ecs_entity_t entity, void* udata);
 
typedef void (*ecs_on_leave_fn)(ecs_t* ecs, ecs_entity_t entity, void* udata);
 
typedef struct
{
    ecs_mask_t mask;
    ecs_on_join_fn on_join_cb;
    ecs_on_leave_fn on_leave_cb;
    void* udata;
} ecs_sys_desc_t;
 
ecs_system_t ecs_define_system(ecs_t* ecs,
                               ecs_system_fn system_cb,
                               const ecs_sys_desc_t* desc);
 
 
void ecs_require(ecs_t* ecs, ecs_system_t sys, ecs_comp_t comp);
 
void ecs_exclude(ecs_t* ecs, ecs_system_t sys, ecs_comp_t comp);
 
void ecs_enable_system(ecs_t* ecs, ecs_system_t sys);
 
void ecs_disable_system(ecs_t* ecs, ecs_system_t sys);
 
void ecs_set_system_callbacks(ecs_t* ecs,
                              ecs_system_t sys,
                              ecs_system_fn system_cb,
                              ecs_on_join_fn on_join,
                              ecs_on_leave_fn on_leave);
 
void ecs_set_system_udata(ecs_t* ecs, ecs_system_t sys, void* udata);
 
void* ecs_get_system_udata(ecs_t* ecs, ecs_system_t sys);
 
void ecs_set_system_mask(ecs_t* ecs, ecs_system_t sys, ecs_mask_t mask);
 
ecs_mask_t ecs_get_system_mask(ecs_t* ecs, ecs_system_t sys);
 
ecs_entity_t* ecs_get_entity_array(ecs_t* ecs, ecs_system_t sys);
 
size_t ecs_get_entity_count(ecs_t* ecs, ecs_system_t sys);
 
ecs_entity_t ecs_create(ecs_t* ecs);
 
bool ecs_is_ready(ecs_t* ecs, ecs_entity_t entity);
 
bool ecs_has(ecs_t* ecs, ecs_entity_t entity, ecs_comp_t comp);
 
void ecs_add(ecs_t* ecs, ecs_entity_t entity, ecs_comp_t comp, void* args);
 
void* ecs_get(ecs_t* ecs, ecs_entity_t entity, ecs_comp_t comp);
 
void ecs_set(ecs_t* ecs, ecs_entity_t entity, ecs_comp_t comp, void* data);
 
void ecs_destroy(ecs_t* ecs, ecs_entity_t entity);
 
void ecs_remove(ecs_t* ecs, ecs_entity_t entity, ecs_comp_t comp);
 
ecs_ret_t ecs_run_system(ecs_t* ecs, ecs_system_t sys, ecs_mask_t mask);
 
ecs_ret_t ecs_run_systems(ecs_t* ecs, ecs_mask_t mask);
 
#ifdef __cplusplus
}
#endif
 
#endif // PICO_ECS_H
 
#ifdef PICO_ECS_IMPLEMENTATION // Define once
 
#ifndef PICO_ECS_MAX_COMPONENTS
#define PICO_ECS_MAX_COMPONENTS 32
#endif
 
#ifndef PICO_ECS_MAX_SYSTEMS
#define PICO_ECS_MAX_SYSTEMS 16
#endif
 
#ifndef PICO_ECS_COMP_BLOCK_SIZE
#define PICO_ECS_COMP_BLOCK_SIZE 64
#endif
 
#ifdef NDEBUG
    #define PICO_ECS_ASSERT(expr) ((void)0)
#else
    #ifndef PICO_ECS_ASSERT
        #include <assert.h>
        #define PICO_ECS_ASSERT(expr) (assert(expr))
    #endif
#endif
 
#if !defined(PICO_ECS_MALLOC) || !defined(PICO_ECS_REALLOC) || !defined(PICO_ECS_FREE)
#include <stdlib.h>
#define PICO_ECS_MALLOC(size, ctx)       (malloc(size))
#define PICO_ECS_REALLOC(ptr, size, ctx) (realloc(ptr, size))
#define PICO_ECS_FREE(ptr, ctx)          (free(ptr))
#endif
 
#ifndef PICO_ECS_MEMSET
    #include <string.h>
    #define PICO_ECS_MEMSET memset
#endif
 
#ifndef PICO_ECS_MEMCPY
    #include <string.h>
    #define PICO_ECS_MEMCPY memcpy
#endif
 
#include <stdalign.h>
 
/*=============================================================================
 *  Aliases>
 *============================================================================*/
 
#define ECS_ASSERT           PICO_ECS_ASSERT
#define ECS_MAX_COMPONENTS   PICO_ECS_MAX_COMPONENTS
#define ECS_MAX_SYSTEMS      PICO_ECS_MAX_SYSTEMS
#define ECS_COMP_BLOCK_SIZE  PICO_ECS_COMP_BLOCK_SIZE
#define ECS_MALLOC           PICO_ECS_MALLOC
#define ECS_REALLOC          PICO_ECS_REALLOC
#define ECS_FREE             PICO_ECS_FREE
#define ECS_MEMSET           PICO_ECS_MEMSET
#define ECS_MEMCPY           PICO_ECS_MEMCPY
 
/*=============================================================================
 *  Data structures
 *============================================================================*/
 
#if ECS_MAX_COMPONENTS <= 32
typedef uint32_t ecs_bitset_t;
#elif ECS_MAX_COMPONENTS <= 64
typedef uint64_t ecs_bitset_t;
#else
#define ECS_BITSET_WIDTH 64
#define ECS_BITSET_SIZE (((ECS_MAX_COMPONENTS - 1) / ECS_BITSET_WIDTH) + 1)
 
typedef struct
{
    uint64_t array[ECS_BITSET_SIZE];
} ecs_bitset_t;
 
#endif // ECS_MAX_COMPONENTS
 
typedef struct ecs_arena_block_s
{
    uint8_t*              memory;
    size_t                size;
    size_t                offset;
    struct ecs_arena_block_s* next;
} ecs_arena_block_t;
 
typedef struct ecs_arena_s
{
    ecs_t* ecs;
    ecs_arena_block_t* first;
    ecs_arena_block_t* current;
    size_t block_size;
} ecs_arena_t;
 
// Data-structure for a packed array implementation that provides O(1) functions
// for adding, removing, and accessing entity IDs
typedef struct
{
    size_t        capacity;
    size_t        size;
    size_t*       sparse;
    ecs_entity_t* dense;
} ecs_sparse_set_t;
 
// A data-structure for providing O(1) operations for working with IDs
typedef struct
{
    size_t    capacity;
    size_t    size; // array size
    ecs_id_t* data;
} ecs_id_array_t;
 
typedef struct
{
    size_t  block_count;    // number of allocated blocks
    size_t  block_capacity; // capacity of the blocks[] pointer array
    size_t  comp_size;      // size of one component in bytes
    void**  blocks;         // array of pointers to fixed-size blocks
} ecs_comp_blocks_t;
 
typedef struct
{
    ecs_bitset_t comp_bits;
    bool         active;
    bool         ready;
} ecs_entity_data_t;
 
typedef struct
{
    ecs_on_add_fn on_add;
    ecs_on_remove_fn on_remove;
    ecs_on_set_fn on_set;
    size_t size;
    void* default_value;
    size_t args_size;
    void* udata;
} ecs_comp_data_t;
 
typedef struct
{
    bool             active;
    ecs_sparse_set_t entity_ids;
    ecs_mask_t       mask;
    ecs_system_fn    system_cb;
    ecs_on_join_fn   on_join;
    ecs_on_leave_fn  on_leave;
    ecs_bitset_t     require_bits;
    ecs_bitset_t     exclude_bits;
    void*            udata;
} ecs_sys_data_t;
 
typedef enum
{
    ECS_CMD_ADD,
    ECS_CMD_REMOVE,
    ECS_CMD_SET,
    ECS_CMD_DESTROY,
} ecs_cmd_type_t;
 
typedef struct
{
    ecs_cmd_type_t type;
    ecs_entity_t   entity;
    ecs_comp_t     comp;
    void*          data;
    void*          args;
} ecs_cmd_t;
 
typedef struct
{
    ecs_cmd_t* data;
    size_t     size;
    size_t     capacity;
} ecs_cmd_array_t;
 
struct ecs_s
{
    ecs_id_array_t     entity_pool;
    ecs_entity_data_t* entities;
    size_t             entity_capacity;
    size_t             next_entity_id;
    ecs_comp_data_t    comps[ECS_MAX_COMPONENTS];
    ecs_comp_blocks_t  comp_blocks[ECS_MAX_COMPONENTS];
    size_t             comp_count;
    ecs_sys_data_t     systems[ECS_MAX_SYSTEMS];
    size_t             system_count;
    bool               system_active;
    ecs_cmd_array_t    cmd_queue;
    ecs_arena_t        arena;
    void*              mem_ctx;
};
 
/*=============================================================================
 * Handle constructors
 *============================================================================*/
static inline ecs_entity_t ecs_make_entity(ecs_id_t id);
static inline ecs_comp_t ecs_make_comp(ecs_id_t id);
static inline ecs_system_t ecs_make_system(ecs_id_t id);
 
/*=============================================================================
 * Realloc wrapper
 *============================================================================*/
static void* ecs_realloc_zero(ecs_t* ecs, void* ptr, size_t old_size, size_t new_size);
 
/*=============================================================================
 * Tests if entity is active (created)
 *============================================================================*/
static inline bool ecs_is_active(ecs_t* ecs, ecs_id_t entity_id);
 
/*=============================================================================
 * Command queue functions
 *============================================================================*/
static void  ecs_cmd_array_init(ecs_t* ecs, ecs_cmd_array_t* queue, size_t capacity);
static void  ecs_cmd_array_free(ecs_t* ecs, ecs_cmd_array_t* queue);
static ecs_cmd_t* ecs_cmd_array_push(ecs_t* ecs, ecs_cmd_array_t* queue);
static void  ecs_cmd_flush_queue(ecs_t* ecs);
 
/*=============================================================================
 * Bitset functions
 *============================================================================*/
static inline void ecs_bitset_flip(ecs_bitset_t* set, int bit, bool on);
static inline bool ecs_bitset_is_zero(ecs_bitset_t* set);
static inline bool ecs_bitset_test(ecs_bitset_t* set, int bit);
static inline ecs_bitset_t ecs_bitset_and(ecs_bitset_t* set1, ecs_bitset_t* set2);
static inline ecs_bitset_t ecs_bitset_or(ecs_bitset_t* set1, ecs_bitset_t* set2);
static inline ecs_bitset_t ecs_bitset_not(ecs_bitset_t* set);
static inline bool ecs_bitset_equal(ecs_bitset_t* set1, ecs_bitset_t* set2);
static inline bool ecs_bitset_true(ecs_bitset_t* set);
 
/*=============================================================================
 * Arena functions
 *============================================================================*/
static ecs_arena_block_t* ecs_arena_block_create(ecs_t* ecs, size_t size);
static bool ecs_arena_init(ecs_t* ecs, ecs_arena_t* arena, size_t initial_block_size);
static bool ecs_arena_grow(ecs_t* ecs, ecs_arena_t* arena, size_t min_size);
static uintptr_t ecs_arena_align_forward(uintptr_t ptr, size_t align);
static void* ecs_arena_alloc_align(ecs_t* ecs, ecs_arena_t* arena, size_t size, size_t align);
static void* ecs_arena_alloc(ecs_t* ecs, ecs_arena_t* arena, size_t size);
static void ecs_arena_reset(ecs_t* ecs, ecs_arena_t* arena);
static void ecs_arena_destroy(ecs_t* ecs, ecs_arena_t* arena);
 
/*=============================================================================
 * Sparse set functions
 *============================================================================*/
static void ecs_sparse_set_init(ecs_t* ecs, ecs_sparse_set_t* set, size_t capacity);
static void ecs_sparse_set_free(ecs_t* ecs, ecs_sparse_set_t* set);
static bool ecs_sparse_set_add(ecs_t* ecs, ecs_sparse_set_t* set, ecs_id_t id);
static inline bool ecs_sparse_set_find(ecs_sparse_set_t* set, ecs_id_t id, size_t* found);
static inline bool ecs_sparse_set_remove(ecs_sparse_set_t* set, ecs_id_t id);
 
/*=============================================================================
 * System entity add/remove functions
 *============================================================================*/
 
static bool ecs_entity_system_test(ecs_bitset_t require_bits,
                                   ecs_bitset_t exclude_bits,
                                   ecs_bitset_t entity_bits);
 
static void ecs_sync_add_remove(ecs_t* ecs, ecs_id_t entity_id, ecs_id_t comp_id);
static void ecs_sync_destroy(ecs_t* ecs, ecs_id_t entity_id);
 
/*=============================================================================
 * ID array functions
 *============================================================================*/
static void   ecs_id_array_init(ecs_t* ecs, ecs_id_array_t* pool, size_t capacity);
static void   ecs_id_array_free(ecs_t* ecs, ecs_id_array_t* pool);
static inline void  ecs_id_array_push(ecs_t* ecs, ecs_id_array_t* pool, ecs_id_t id);
static inline ecs_id_t ecs_id_array_pop(ecs_id_array_t* pool);
static inline size_t ecs_id_array_size(ecs_id_array_t* pool);
 
/*=============================================================================
 * Component array functions
 *============================================================================*/
static void ecs_comp_blocks_init(ecs_t* ecs, ecs_comp_blocks_t* array, size_t size, size_t capacity);
static void ecs_comp_blocks_free(ecs_t* ecs, ecs_comp_blocks_t* array);
static void ecs_comp_blocks_resize(ecs_t* ecs, ecs_comp_blocks_t* array, ecs_id_t id);
 
/*=============================================================================
 * Validation functions
 *============================================================================*/
#ifndef NDEBUG
static bool ecs_is_not_null(void* ptr);
static bool ecs_is_valid_component_id(ecs_id_t id);
static bool ecs_is_valid_system_id(ecs_id_t id);
static bool ecs_is_valid_id(ecs_id_t id);
static bool ecs_is_valid_capacity(size_t capacity, size_t elem_size);
static bool ecs_is_entity_ready(ecs_t* ecs, ecs_id_t entity_id);
static bool ecs_is_component_ready(ecs_t* ecs, ecs_id_t comp_id);
static bool ecs_is_system_ready(ecs_t* ecs, ecs_id_t sys_id);
#endif // NDEBUG
 
/*=============================================================================
 * Public API implementation
 *============================================================================*/
 
ecs_t* ecs_new(size_t entity_capacity, void* mem_ctx)
{
    ECS_ASSERT(entity_capacity > 0);
    ECS_ASSERT(!ecs_is_valid_id(ECS_INVALID_ID) && "ecs_id_t is signed");
 
    ecs_t* ecs = (ecs_t*)ECS_MALLOC(sizeof(ecs_t), mem_ctx);
 
    // Out of memory
    if (NULL == ecs)
        return NULL;
 
    ECS_MEMSET(ecs, 0, sizeof(ecs_t));
 
    ecs->entity_capacity = (entity_capacity > 0) ? entity_capacity : 32;
    ecs->next_entity_id  = 0;
    ecs->system_active   = false;
    ecs->mem_ctx         = mem_ctx;
 
    // Initialize entity pool and queues
    ecs_id_array_init(ecs, &ecs->entity_pool, entity_capacity);
 
    // Initialize deferred command queue
    ecs_cmd_array_init(ecs, &ecs->cmd_queue, entity_capacity);
 
    // Allocate entity array
    ECS_ASSERT(ecs_is_valid_capacity(ecs->entity_capacity, sizeof(ecs_entity_data_t)));
    ecs->entities = (ecs_entity_data_t*)ECS_MALLOC(ecs->entity_capacity * sizeof(ecs_entity_data_t),
                                                   ecs->mem_ctx);
 
    // Zero entity array
    ECS_MEMSET(ecs->entities, 0, ecs->entity_capacity * sizeof(ecs_entity_data_t));
 
    ecs_arena_init(ecs, &ecs->arena, 512);
 
    return ecs;
}
 
void ecs_free(ecs_t* ecs)
{
    ECS_ASSERT(ecs_is_not_null(ecs));
 
    ecs_id_array_free(ecs, &ecs->entity_pool);
    ecs_cmd_array_free(ecs, &ecs->cmd_queue);
    ecs_arena_destroy(ecs, &ecs->arena);
 
    for (ecs_id_t comp_id = 0; comp_id < ecs->comp_count; comp_id++)
    {
        ecs_comp_blocks_t* comp_blocks = &ecs->comp_blocks[comp_id];
        ecs_comp_blocks_free(ecs, comp_blocks);
    }
 
    for (ecs_id_t sys_id = 0; sys_id < ecs->system_count; sys_id++)
    {
        ecs_sys_data_t* sys = &ecs->systems[sys_id];
        ecs_sparse_set_free(ecs, &sys->entity_ids);
    }
 
    for (ecs_id_t comp_id = 0; comp_id < ecs->comp_count; comp_id++)
    {
        ecs_comp_data_t* comp_data = &ecs->comps[comp_id];
 
        if (comp_data->default_value)
        {
            ECS_FREE(comp_data->default_value, ecs->mem_ctx);
        }
    }
 
    ECS_FREE(ecs->entities, ecs->mem_ctx);
    ECS_FREE(ecs, ecs->mem_ctx);
}
 
void ecs_reset(ecs_t* ecs)
{
    ECS_ASSERT(ecs_is_not_null(ecs));
 
    ecs->entity_pool.size = 0;
 
    ECS_MEMSET(ecs->entities, 0, ecs->entity_capacity * sizeof(ecs_entity_data_t));
 
    ecs->next_entity_id = 0;
 
    for (ecs_id_t sys_id = 0; sys_id < ecs->system_count; sys_id++)
    {
        ecs->systems[sys_id].entity_ids.size = 0;
    }
}
 
ecs_comp_t ecs_define_component(ecs_t* ecs,
                                size_t size,
                                const ecs_comp_desc_t* desc)
{
    ECS_ASSERT(ecs_is_not_null(ecs));
    ECS_ASSERT(ecs->comp_count < ECS_MAX_COMPONENTS);
    ECS_ASSERT(size > 0);
 
    ecs_comp_t comp = ecs_make_comp(ecs->comp_count);
 
    ecs_comp_blocks_t* comp_blocks = &ecs->comp_blocks[comp.id];
    ecs_comp_blocks_init(ecs, comp_blocks, size, ecs->entity_capacity);
 
    ecs_comp_data_t* comp_data = &ecs->comps[comp.id];
 
    ECS_MEMSET(comp_data, 0, sizeof(ecs_comp_data_t));
    comp_data->size = size;
 
    if (desc)
    {
        comp_data->on_add = desc->on_add_cb;
        comp_data->on_remove = desc->on_remove_cb;
        comp_data->on_set = desc->on_set_cb;
        comp_data->args_size = desc->args_size;
        comp_data->udata = desc->udata;
 
        if (desc->default_value)
        {
            comp_data->default_value = ECS_MALLOC(size, ctx->mem_ctx);
            ECS_MEMCPY(comp_data->default_value, desc->default_value, size);
        }
    }
 
    ecs->comp_count++;
 
    return comp;
}
 
ecs_system_t ecs_define_system(ecs_t* ecs,
                               ecs_system_fn system_cb,
                               const ecs_sys_desc_t* desc)
{
    ECS_ASSERT(ecs_is_not_null(ecs));
    ECS_ASSERT(ecs->system_count < ECS_MAX_SYSTEMS);
    ECS_ASSERT(NULL != system_cb);
 
    ecs_system_t sys = ecs_make_system(ecs->system_count);
    ecs_sys_data_t* sys_data = &ecs->systems[sys.id];
 
    ECS_MEMSET(sys_data, 0, sizeof(ecs_sys_data_t));
 
    ecs_sparse_set_init(ecs, &sys_data->entity_ids, ecs->entity_capacity);
 
    sys_data->system_cb = system_cb;
    sys_data->active = true;
 
    if (desc)
    {
        sys_data->mask = desc->mask;
        sys_data->on_join = desc->on_join_cb;
        sys_data->on_leave = desc->on_leave_cb;
        sys_data->udata = desc->udata;
    }
 
    ecs->system_count++;
 
    return sys;
}
 
void ecs_require(ecs_t* ecs, ecs_system_t sys, ecs_comp_t comp)
{
    ECS_ASSERT(ecs_is_not_null(ecs));
    ECS_ASSERT(ecs_is_valid_system_id(sys.id));
    ECS_ASSERT(ecs_is_valid_component_id(comp.id));
    ECS_ASSERT(ecs_is_system_ready(ecs, sys.id));
    ECS_ASSERT(ecs_is_component_ready(ecs, comp.id));
 
    // Set system component bit for the specified component
    ecs_sys_data_t* sys_data = &ecs->systems[sys.id];
    ecs_bitset_flip(&sys_data->require_bits, comp.id, true);
}
 
void ecs_exclude(ecs_t* ecs, ecs_system_t sys, ecs_comp_t comp)
{
    ECS_ASSERT(ecs_is_not_null(ecs));
    ECS_ASSERT(ecs_is_valid_system_id(sys.id));
    ECS_ASSERT(ecs_is_valid_component_id(comp.id));
    ECS_ASSERT(ecs_is_system_ready(ecs, sys.id));
    ECS_ASSERT(ecs_is_component_ready(ecs, comp.id));
 
    // Set system component bit for the specified component
    ecs_sys_data_t* sys_data = &ecs->systems[sys.id];
    ecs_bitset_flip(&sys_data->exclude_bits, comp.id, true);
}
 
void ecs_enable_system(ecs_t* ecs, ecs_system_t sys)
{
    ECS_ASSERT(ecs_is_not_null(ecs));
    ECS_ASSERT(ecs_is_valid_system_id(sys.id));
    ECS_ASSERT(ecs_is_system_ready(ecs, sys.id));
 
    ecs_sys_data_t* sys_data = &ecs->systems[sys.id];
    sys_data->active = true;
}
 
void ecs_disable_system(ecs_t* ecs, ecs_system_t sys)
{
    ECS_ASSERT(ecs_is_not_null(ecs));
    ECS_ASSERT(ecs_is_valid_system_id(sys.id));
    ECS_ASSERT(ecs_is_system_ready(ecs, sys.id));
 
    ecs_sys_data_t* sys_data = &ecs->systems[sys.id];
    sys_data->active = false;
}
 
void ecs_set_system_callbacks(ecs_t* ecs,
                              ecs_system_t sys,
                              ecs_system_fn system_cb,
                              ecs_on_join_fn on_join,
                              ecs_on_leave_fn on_leave)
{
    ECS_ASSERT(ecs_is_not_null(ecs));
    ECS_ASSERT(ecs_is_valid_system_id(sys.id));
    ECS_ASSERT(ecs_is_system_ready(ecs, sys.id));
    ECS_ASSERT(NULL != system_cb);
 
    ecs_sys_data_t* sys_data = &ecs->systems[sys.id];
    sys_data->system_cb = system_cb;
    sys_data->on_join = on_join;
    sys_data->on_leave = on_leave;
}
 
void ecs_set_system_udata(ecs_t* ecs, ecs_system_t sys, void* udata)
{
    ECS_ASSERT(ecs_is_not_null(ecs));
    ECS_ASSERT(ecs_is_valid_system_id(sys.id));
    ECS_ASSERT(ecs_is_system_ready(ecs, sys.id));
 
    ecs->systems[sys.id].udata = udata;
}
 
void* ecs_get_system_udata(ecs_t* ecs, ecs_system_t sys)
{
    ECS_ASSERT(ecs_is_not_null(ecs));
    ECS_ASSERT(ecs_is_valid_system_id(sys.id));
    ECS_ASSERT(ecs_is_system_ready(ecs, sys.id));
 
    return ecs->systems[sys.id].udata;
}
 
void ecs_set_system_mask(ecs_t* ecs, ecs_system_t sys, ecs_mask_t mask)
{
    ECS_ASSERT(ecs_is_not_null(ecs));
    ECS_ASSERT(ecs_is_valid_system_id(sys.id));
    ECS_ASSERT(ecs_is_system_ready(ecs, sys.id));
 
    ecs->systems[sys.id].mask = mask;
}
 
ecs_mask_t ecs_get_system_mask(ecs_t* ecs, ecs_system_t sys)
{
    ECS_ASSERT(ecs_is_not_null(ecs));
    ECS_ASSERT(ecs_is_valid_system_id(sys.id));
    ECS_ASSERT(ecs_is_system_ready(ecs, sys.id));
 
    return ecs->systems[sys.id].mask;
}
 
ecs_entity_t* ecs_get_entity_array(ecs_t* ecs, ecs_system_t sys)
{
    ECS_ASSERT(ecs_is_not_null(ecs));
    ECS_ASSERT(ecs_is_valid_system_id(sys.id));
    ECS_ASSERT(ecs_is_system_ready(ecs, sys.id));
 
    return ecs->systems[sys.id].entity_ids.dense;
}
 
size_t ecs_get_entity_count(ecs_t* ecs, ecs_system_t sys)
{
    ECS_ASSERT(ecs_is_not_null(ecs));
    ECS_ASSERT(ecs_is_valid_system_id(sys.id));
    ECS_ASSERT(ecs_is_system_ready(ecs, sys.id));
 
    return ecs->systems[sys.id].entity_ids.size;
}
 
ecs_entity_t ecs_create(ecs_t* ecs)
{
    ECS_ASSERT(ecs_is_not_null(ecs));
 
    ecs_id_t entity_id = 0;
 
    // If there is an ID in the pool, pop it
    ecs_id_array_t* pool = &ecs->entity_pool;
 
    if (0 != ecs_id_array_size(pool))
    {
        entity_id = ecs_id_array_pop(pool);
    }
    else
    {
        // Otherwise, issue a fresh ID
        entity_id = ecs->next_entity_id++;
 
        // Grow the entities array if necessary
        if (entity_id >= ecs->entity_capacity)
        {
            size_t old_capacity = ecs->entity_capacity;
            size_t new_capacity = 2 * old_capacity;
 
            ECS_ASSERT(ecs_is_valid_capacity(new_capacity, sizeof(ecs_entity_data_t)));
            ecs->entities = (ecs_entity_data_t*)ecs_realloc_zero(ecs, ecs->entities,
                                                                 old_capacity * sizeof(ecs_entity_data_t),
                                                                 new_capacity * sizeof(ecs_entity_data_t));
 
            ecs->entity_capacity = new_capacity;
        }
    }
 
    // Activate the entity and return a handle
    ecs->entities[entity_id].active = true;
    ecs->entities[entity_id].ready  = true;
 
    return ecs_make_entity(entity_id);
}
 
bool ecs_is_ready(ecs_t* ecs, ecs_entity_t entity)
{
    ECS_ASSERT(ecs_is_not_null(ecs));
 
    return ecs->entities[entity.id].ready;
}
 
void ecs_set(ecs_t* ecs, ecs_entity_t entity, ecs_comp_t comp, void* data)
{
    ECS_ASSERT(ecs_is_not_null(ecs));
    ECS_ASSERT(ecs_is_valid_id(entity.id));
    ECS_ASSERT(ecs_is_valid_component_id(comp.id));
    ECS_ASSERT(ecs_is_component_ready(ecs, comp.id));
    ECS_ASSERT(ecs_is_entity_ready(ecs, entity.id));
 
    if (!ecs_has(ecs, entity, comp))
    {
        ecs_add(ecs, entity, comp, NULL);
    }
 
    ecs_comp_data_t* comp_data = &ecs->comps[comp.id];
 
    if (ecs->system_active)
    {
        ecs_cmd_t* cmd = ecs_cmd_array_push(ecs, &ecs->cmd_queue);
        cmd->type   = ECS_CMD_SET;
        cmd->entity = entity;
        cmd->comp   = comp;
        cmd->data   = ecs_arena_alloc(ecs, &ecs->arena, comp_data->size);
        ECS_MEMCPY(cmd->data, data, comp_data->size);
        return;
    }
 
    void* comp_ptr = ecs_get(ecs, entity, comp);
    ECS_MEMCPY(comp_ptr, data, comp_data->size);
 
    // Callback
    if (comp_data->on_set)
        comp_data->on_set(ecs, entity, comp, comp_data->udata);
}
 
void ecs_destroy(ecs_t* ecs, ecs_entity_t entity)
{
    ECS_ASSERT(ecs_is_not_null(ecs));
    ECS_ASSERT(ecs_is_valid_id(entity.id));
    ECS_ASSERT(ecs_is_active(ecs, entity.id));
 
    if (!ecs_is_active(ecs, entity.id))
        return;
 
    ecs_entity_data_t* entity_data = &ecs->entities[entity.id];
    ecs_bitset_t comp_bits = entity_data->comp_bits;
 
    if (ecs->system_active)
    {
        ecs_cmd_t* cmd = ecs_cmd_array_push(ecs, &ecs->cmd_queue);
        cmd->type   = ECS_CMD_DESTROY;
        cmd->entity = entity;
        ecs->entities[entity.id].ready = false;
        return;
    }
 
    for (ecs_id_t comp_id = 0; comp_id < ecs->comp_count; comp_id++)
    {
        if (ecs_bitset_test(&comp_bits, comp_id))
        {
            ecs_comp_data_t* comp_data = &ecs->comps[comp_id];
 
            if (comp_data->on_remove)
            {
                ecs_comp_t comp = ecs_make_comp(comp_id);
                comp_data->on_remove(ecs, entity, comp, comp_data->udata);
            }
        }
    }
 
    ecs_sync_destroy(ecs, entity.id);
 
    ecs_id_array_t* pool = &ecs->entity_pool;
    ecs_id_array_push(ecs, pool, entity.id);
 
    ECS_MEMSET(&entity_data->comp_bits, 0, sizeof(ecs_bitset_t));
    entity_data->active = false;
    entity_data->ready  = false;
}
 
bool ecs_has(ecs_t* ecs, ecs_entity_t entity, ecs_comp_t comp)
{
    ECS_ASSERT(ecs_is_not_null(ecs));
    ECS_ASSERT(ecs_is_valid_id(entity.id));
    ECS_ASSERT(ecs_is_valid_component_id(comp.id));
 
    // Load entity data
    ecs_entity_data_t* entity_data = &ecs->entities[entity.id];
 
    if (!entity_data->ready)
        return false;
 
    // Return true if the component belongs to the entity
    return ecs_bitset_test(&entity_data->comp_bits, comp.id);
}
 
void* ecs_get(ecs_t* ecs, ecs_entity_t entity, ecs_comp_t comp)
{
    ECS_ASSERT(ecs_is_not_null(ecs));
    ECS_ASSERT(ecs_is_valid_id(entity.id));
    ECS_ASSERT(ecs_is_valid_component_id(comp.id));
    ECS_ASSERT(ecs_is_component_ready(ecs, comp.id));
    ECS_ASSERT(ecs_is_entity_ready(ecs, entity.id));
 
    // Map entity ID to block and slot within that block.
    // Blocks are never reallocated, so returned pointers remain stable.
    ecs_comp_blocks_t* comp_blocks = &ecs->comp_blocks[comp.id];
 
    size_t block = entity.id / ECS_COMP_BLOCK_SIZE;
    size_t slot  = entity.id % ECS_COMP_BLOCK_SIZE;
 
    return (char*)comp_blocks->blocks[block] + (comp_blocks->comp_size * slot);
}
 
void ecs_add(ecs_t* ecs, ecs_entity_t entity, ecs_comp_t comp, void* args)
{
    ECS_ASSERT(ecs_is_not_null(ecs));
    ECS_ASSERT(ecs_is_valid_id(entity.id));
    ECS_ASSERT(ecs_is_valid_component_id(comp.id));
    ECS_ASSERT(ecs_is_entity_ready(ecs, entity.id));
    ECS_ASSERT(ecs_is_component_ready(ecs, comp.id));
 
    if (ecs_has(ecs, entity, comp))
        return;
 
    // Load entity data
    ecs_entity_data_t* entity_data = &ecs->entities[entity.id];
 
    // Set entity component bit that determines which systems this entity
    // belongs to
    ecs_bitset_flip(&entity_data->comp_bits, comp.id, true);
 
    // Load component
    ecs_comp_blocks_t* comp_blocks = &ecs->comp_blocks[comp.id];
 
    // Grow the component array now (not deferred) so that ecs_get can safely
    // index into it immediately, since ecs_has already reports the component
    // as present as soon as the bit above is flipped
    ecs_comp_blocks_resize(ecs, comp_blocks, entity.id);
 
    ecs_comp_data_t* comp_data = &ecs->comps[comp.id];
 
    if (ecs->system_active)
    {
        ecs_cmd_t* cmd = ecs_cmd_array_push(ecs, &ecs->cmd_queue);
        cmd->type      = ECS_CMD_ADD;
        cmd->entity    = entity;
        cmd->comp      = comp;
 
        // Copy the constructor args into the command arena so the caller is
        // not required to keep them alive until the queue is flushed. The copy
        // is handed back to ecs_add (and thus the on_add constructor) when the
        // queue is flushed at the end of the system run.
        if (args && comp_data->args_size > 0)
        {
            cmd->args = ecs_arena_alloc(ecs, &ecs->arena, comp_data->args_size);
            ECS_MEMCPY(cmd->args, args, comp_data->args_size);
        }
 
        return;
    }
 
    // Get pointer to component
    void* comp_ptr = ecs_get(ecs, entity, comp);
 
    // Set default value
    if (comp_data->default_value)
        ECS_MEMCPY(comp_ptr, comp_data->default_value, comp_data->size);
    else
        ECS_MEMSET(comp_ptr, 0, comp_blocks->comp_size);
 
    // Call constructor
    if (comp_data->on_add)
        comp_data->on_add(ecs, entity, comp, args, comp_data->udata);
 
    // Add/remove entity to/from systems based on matching criteria
    ecs_sync_add_remove(ecs, entity.id, comp.id);
}
 
void ecs_remove(ecs_t* ecs, ecs_entity_t entity, ecs_comp_t comp)
{
    ECS_ASSERT(ecs_is_not_null(ecs));
    ECS_ASSERT(ecs_is_valid_id(entity.id));
    ECS_ASSERT(ecs_is_valid_component_id(comp.id));
    ECS_ASSERT(ecs_is_component_ready(ecs, comp.id));
    ECS_ASSERT(ecs_is_entity_ready(ecs, entity.id));
 
    if (!ecs_has(ecs, entity, comp))
        return;
 
    // Load entity data
    ecs_entity_data_t* entity_data = &ecs->entities[entity.id];
 
    // Set entity component bit that determines which systems this entity
    // belongs to
    ecs_bitset_flip(&entity_data->comp_bits, comp.id, false);
 
    if (ecs->system_active)
    {
        ecs_cmd_t* cmd = ecs_cmd_array_push(ecs, &ecs->cmd_queue);
        cmd->type   = ECS_CMD_REMOVE;
        cmd->entity = entity;
        cmd->comp   = comp;
        return;
    }
 
    // Fire callback
    ecs_comp_data_t* comp_data = &ecs->comps[comp.id];
 
    if (comp_data->on_remove)
        comp_data->on_remove(ecs, entity, comp, comp_data->udata);
 
    // Add/remove entity to/from systems based on matching criteria
    ecs_sync_add_remove(ecs, entity.id, comp.id);
}
 
ecs_ret_t ecs_run_system(ecs_t* ecs, ecs_system_t sys, ecs_mask_t mask)
{
    ECS_ASSERT(ecs_is_not_null(ecs));
    ECS_ASSERT(ecs_is_valid_system_id(sys.id));
    ECS_ASSERT(ecs_is_system_ready(ecs, sys.id));
 
    ecs_sys_data_t* sys_data = &ecs->systems[sys.id];
 
    if (!sys_data->active)
        return 0;
 
    if (0 != sys_data->mask && !(sys_data->mask & mask))
        return 0;
 
    ecs->system_active = true;
 
    ecs_ret_t code = sys_data->system_cb(ecs,
                     sys_data->entity_ids.dense,
                     sys_data->entity_ids.size,
                     sys_data->udata);
 
    ecs->system_active = false;
 
    ecs_cmd_flush_queue(ecs);
    ecs_arena_reset(ecs, &ecs->arena);
 
    return code;
}
 
ecs_ret_t ecs_run_systems(ecs_t* ecs, ecs_mask_t mask)
{
    ECS_ASSERT(ecs_is_not_null(ecs));
 
    for (ecs_id_t sys_id = 0; sys_id < ecs->system_count; sys_id++)
    {
        ecs_system_t sys = ecs_make_system(sys_id);
        ecs_ret_t code = ecs_run_system(ecs, sys, mask);
 
        if (0 != code)
            return code;
    }
 
    return 0;
}
 
/*=============================================================================
 * Handle constructors
 *============================================================================*/
static inline ecs_entity_t ecs_make_entity(ecs_id_t id)
{
    return (ecs_entity_t){ id };
}
 
static inline ecs_comp_t ecs_make_comp(ecs_id_t id)
{
    return (ecs_comp_t){ id };
}
 
static inline ecs_system_t ecs_make_system(ecs_id_t id)
{
    return (ecs_system_t){ id };
}
 
/*=============================================================================
 * Realloc wrapper
 *============================================================================*/
static void* ecs_realloc_zero(ecs_t* ecs, void* ptr, size_t old_size, size_t new_size)
{
    (void)ecs;
 
    ptr = ECS_REALLOC(ptr, new_size, ecs->mem_ctx);
 
    if (new_size > old_size && ptr) {
        size_t diff = new_size - old_size;
        void* start = ((char*)ptr)+ old_size;
        ECS_MEMSET(start, 0, diff);
    }
 
    return ptr;
}
 
/*=============================================================================
 * Tests if entity is active (created)
 *============================================================================*/
static inline bool ecs_is_active(ecs_t* ecs, ecs_id_t entity_id)
{
    ECS_ASSERT(ecs_is_not_null(ecs));
    return ecs->entities[entity_id].active;
}
 
/*=============================================================================
 * Command queue implementation
 *============================================================================*/
static void ecs_cmd_array_init(ecs_t* ecs, ecs_cmd_array_t* queue, size_t capacity)
{
    ECS_ASSERT(ecs_is_not_null(ecs));
    ECS_ASSERT(ecs_is_not_null(queue));
    ECS_ASSERT(capacity > 0);
 
    (void)ecs;
 
    queue->size     = 0;
    queue->capacity = capacity;
    queue->data     = (ecs_cmd_t*)ECS_MALLOC(capacity * sizeof(ecs_cmd_t), ecs->mem_ctx);
 
    ECS_ASSERT(ecs_is_not_null(queue->data));
}
 
static void ecs_cmd_array_free(ecs_t* ecs, ecs_cmd_array_t* queue)
{
    ECS_ASSERT(ecs_is_not_null(ecs));
    ECS_ASSERT(ecs_is_not_null(queue));
    ECS_FREE(queue->data, ecs->mem_ctx);
    (void)ecs;
    (void)queue;
}
 
static ecs_cmd_t* ecs_cmd_array_push(ecs_t* ecs, ecs_cmd_array_t* queue)
{
    ECS_ASSERT(ecs_is_not_null(ecs));
    ECS_ASSERT(ecs_is_not_null(queue));
 
    (void)ecs;
 
    if (queue->size == queue->capacity)
    {
        size_t new_capacity = queue->capacity * 2;
 
        ECS_ASSERT(ecs_is_valid_capacity(new_capacity, sizeof(ecs_cmd_t)));
        queue->data = (ecs_cmd_t*)ECS_REALLOC(queue->data,
                                              new_capacity * sizeof(ecs_cmd_t),
                                              ecs->mem_ctx);
        queue->capacity = new_capacity;
    }
 
    ecs_cmd_t* cmd = &queue->data[queue->size++];
    ECS_MEMSET(cmd, 0, sizeof(ecs_cmd_t));
    return cmd;
}
 
static void ecs_cmd_flush_queue(ecs_t* ecs)
{
    ECS_ASSERT(ecs_is_not_null(ecs));
 
    ecs_cmd_array_t* queue = &ecs->cmd_queue;
 
    for (size_t i = 0; i < queue->size; ++i)
    {
        ecs_cmd_t* cmd = &queue->data[i];
 
        switch (cmd->type)
        {
            case ECS_CMD_SET:
                if (ecs_is_ready(ecs, cmd->entity))
                {
                    ecs_set(ecs, cmd->entity, cmd->comp, cmd->data);
                }
                break;
 
            case ECS_CMD_ADD:
                if (ecs_is_ready(ecs, cmd->entity))
                {
                    ecs_bitset_flip(&ecs->entities[cmd->entity.id].comp_bits, cmd->comp.id, false);
                    ecs_add(ecs, cmd->entity, cmd->comp, cmd->args);
                }
                break;
 
            case ECS_CMD_REMOVE:
                if (ecs_is_ready(ecs, cmd->entity))
                {
                    ecs_bitset_flip(&ecs->entities[cmd->entity.id].comp_bits, cmd->comp.id, true);
                    ecs_remove(ecs, cmd->entity, cmd->comp);
                }
                break;
 
            case ECS_CMD_DESTROY:
                if (ecs_is_active(ecs, cmd->entity.id))
                {
                    ecs->entities[cmd->entity.id].ready = true;
                    ecs_destroy(ecs, cmd->entity);
                }
                break;
        }
    }
 
    queue->size = 0;
}
 
/*=============================================================================
 * Bitset functions
 *============================================================================*/
 
#if ECS_MAX_COMPONENTS <= 64
 
static inline bool ecs_bitset_is_zero(ecs_bitset_t* set)
{
    return *set == 0;
}
 
static inline void ecs_bitset_flip(ecs_bitset_t* set, int bit, bool on)
{
    if (on)
        *set |=  ((uint64_t)1 << bit);
    else
        *set &= ~((uint64_t)1 << bit);
}
 
static inline bool ecs_bitset_test(ecs_bitset_t* set, int bit)
{
    return *set & ((uint64_t)1 << bit);
}
 
static inline ecs_bitset_t ecs_bitset_and(ecs_bitset_t* set1, ecs_bitset_t* set2)
{
    return *set1 & *set2;
}
 
static inline ecs_bitset_t ecs_bitset_or(ecs_bitset_t* set1, ecs_bitset_t* set2)
{
    return *set1 | *set2;
}
 
static inline ecs_bitset_t ecs_bitset_not(ecs_bitset_t* set)
{
    return ~(*set);
}
 
static inline bool ecs_bitset_equal(ecs_bitset_t* set1, ecs_bitset_t* set2)
{
    return *set1 == *set2;
}
 
static inline bool ecs_bitset_true(ecs_bitset_t* set)
{
    return *set;
}
 
#else // ECS_MAX_COMPONENTS
 
static inline bool ecs_bitset_is_zero(ecs_bitset_t* set)
{
    for (int i = 0; i < ECS_BITSET_SIZE; i++)
    {
        if (set->array[i] != 0)
            return false;
    }
 
    return true;
}
 
static inline void ecs_bitset_flip(ecs_bitset_t* set, int bit, bool on)
{
    int index = bit / ECS_BITSET_WIDTH;
 
    if (on)
        set->array[index] |=  ((uint64_t)1 << bit % ECS_BITSET_WIDTH);
    else
        set->array[index] &= ~((uint64_t)1 << bit % ECS_BITSET_WIDTH);
}
 
static inline bool ecs_bitset_test(ecs_bitset_t* set, int bit)
{
    int index = bit / ECS_BITSET_WIDTH;
    return set->array[index] & ((uint64_t)1 << bit % ECS_BITSET_WIDTH);
}
 
static inline ecs_bitset_t ecs_bitset_and(ecs_bitset_t* set1,
                                          ecs_bitset_t* set2)
{
    ecs_bitset_t set;
 
    for (int i = 0; i < ECS_BITSET_SIZE; i++)
    {
        set.array[i] = set1->array[i] & set2->array[i];
    }
 
    return set;
}
 
static inline ecs_bitset_t ecs_bitset_or(ecs_bitset_t* set1,
                                         ecs_bitset_t* set2)
{
    ecs_bitset_t set;
 
    for (int i = 0; i < ECS_BITSET_SIZE; i++)
    {
        set.array[i] = set1->array[i] | set2->array[i];
    }
 
    return set;
}
 
static inline ecs_bitset_t ecs_bitset_not(ecs_bitset_t* set)
{
    ecs_bitset_t out;
 
    for (int i = 0; i < ECS_BITSET_SIZE; i++)
    {
        out.array[i] = ~set->array[i];
    }
 
    return out;
}
 
static inline bool ecs_bitset_equal(ecs_bitset_t* set1, ecs_bitset_t* set2)
{
    for (int i = 0; i < ECS_BITSET_SIZE; i++)
    {
        if (set1->array[i] != set2->array[i])
        {
            return false;
        }
    }
 
    return true;
}
 
static inline bool ecs_bitset_true(ecs_bitset_t* set)
{
    for (int i = 0; i < ECS_BITSET_SIZE; i++)
    {
        if (set->array[i])
            return true;
    }
 
    return false;
}
 
#endif // ECS_MAX_COMPONENTS
 
static ecs_arena_block_t* ecs_arena_block_create(ecs_t* ecs, size_t size)
{
    (void)ecs;
 
    ecs_arena_block_t* block = (ecs_arena_block_t*)ECS_MALLOC(sizeof(ecs_arena_block_t), ecs->mem_ctx);
 
    if (!block)
        return NULL;
 
    block->memory = (uint8_t*)ECS_MALLOC(size, ecs->mem_ctx);
 
    if (!block->memory)
    {
        ECS_FREE(block, ecs->mem_ctx);
        return NULL;
    }
 
    block->size   = size;
    block->offset = 0;
    block->next   = NULL;
 
    return block;
}
 
static bool ecs_arena_init(ecs_t* ecs, ecs_arena_t* arena, size_t initial_block_size)
{
    ecs_arena_block_t* block = ecs_arena_block_create(ecs, initial_block_size);
 
    if (!block)
        return false;
 
    arena->first      = block;
    arena->current    = block;
    arena->block_size = initial_block_size;
 
    return true;
}
 
static bool ecs_arena_grow(ecs_t* ecs, ecs_arena_t* arena, size_t min_size)
{
    size_t new_size = arena->block_size;
 
    while (new_size < min_size)
    {
        new_size *= 2;
    }
 
    ecs_arena_block_t* block = ecs_arena_block_create(ecs, new_size);
 
    if (!block)
        return false;
 
    arena->current->next = block;
    arena->current       = block;
 
    return true;
}
 
static uintptr_t ecs_arena_align_forward(uintptr_t ptr, size_t align)
{
    uintptr_t mask = (uintptr_t)align - 1;
    return (ptr + mask) & ~mask;
}
 
static void* ecs_arena_alloc_align(ecs_t* ecs, ecs_arena_t* arena, size_t size, size_t align)
{
    if ((align & (align - 1)) != 0)
        return NULL; // align must be a power of two
 
    ecs_arena_block_t* block = arena->current;
 
    uintptr_t base      = (uintptr_t)block->memory;
    uintptr_t ptr       = base + block->offset;
    uintptr_t aligned   = ecs_arena_align_forward(ptr, align);
    size_t    new_offset = (aligned - base) + size;
 
    if (new_offset > block->size)
    {
        size_t required = size + align;
 
        if (!ecs_arena_grow(ecs, arena, required))
            return NULL;
 
        block      = arena->current;
        base       = (uintptr_t)block->memory;
        aligned    = ecs_arena_align_forward(base, align);
        new_offset = (aligned - base) + size;
    }
 
    block->offset = new_offset;
 
    return (void*)aligned;
}
 
static void* ecs_arena_alloc(ecs_t* ecs, ecs_arena_t* arena, size_t size)
{
    return ecs_arena_alloc_align(ecs, arena, size, alignof(max_align_t));
}
 
static void ecs_arena_reset(ecs_t* ecs, ecs_arena_t* arena)
{
    (void)ecs;
 
    ecs_arena_block_t* block = arena->first->next;
 
    while (block)
    {
        ecs_arena_block_t* next = block->next;
        ECS_FREE(block->memory, ecs->mem_ctx);
        ECS_FREE(block, ecs->mem_ctx);
        block = next;
    }
 
    arena->first->next   = NULL;
    arena->first->offset = 0;
    arena->current       = arena->first;
}
 
static void ecs_arena_destroy(ecs_t* ecs, ecs_arena_t* arena)
{
    (void)ecs;
 
    ecs_arena_block_t* block = arena->first;
 
    while (block)
    {
        ecs_arena_block_t* next = block->next;
        ECS_FREE(block->memory, ecs->mem_ctx);
        ECS_FREE(block, ecs->mem_ctx);
        block = next;
    }
 
    arena->first   = NULL;
    arena->current = NULL;
}
 
/*=============================================================================
 * Sparse set functions
 *============================================================================*/
 
static void ecs_sparse_set_init(ecs_t* ecs, ecs_sparse_set_t* set, size_t capacity)
{
    ECS_ASSERT(ecs_is_not_null(ecs));
    ECS_ASSERT(ecs_is_not_null(set));
 
    (void)ecs;
 
    set->capacity = capacity;
    set->size = 0;
 
    ECS_ASSERT(ecs_is_valid_capacity(capacity, sizeof(ecs_entity_t)));
    set->dense  = (ecs_entity_t*)ECS_MALLOC(capacity * sizeof(ecs_entity_t), ecs->mem_ctx);
 
    ECS_ASSERT(ecs_is_valid_capacity(capacity, sizeof(size_t)));
    set->sparse = (size_t*)      ECS_MALLOC(capacity * sizeof(size_t),   ecs->mem_ctx);
 
    ECS_MEMSET(set->sparse, 0, capacity * sizeof(size_t));
}
 
static void ecs_sparse_set_free(ecs_t* ecs, ecs_sparse_set_t* set)
{
    ECS_ASSERT(ecs_is_not_null(ecs));
    ECS_ASSERT(ecs_is_not_null(set));
 
    (void)ecs;
 
    ECS_FREE(set->dense,  ecs->mem_ctx);
    ECS_FREE(set->sparse, ecs->mem_ctx);
}
 
static bool ecs_sparse_set_add(ecs_t* ecs, ecs_sparse_set_t* set, ecs_id_t id)
{
    ECS_ASSERT(ecs_is_not_null(ecs));
    ECS_ASSERT(ecs_is_not_null(set));
    ECS_ASSERT(ecs_is_valid_id(id));
 
    (void)ecs;
 
    // Check if ID exists within the set
    if (ecs_sparse_set_find(set, id, NULL))
        return false;
 
    // Grow sparse set if necessary
    if (id >= set->capacity)
    {
        size_t old_capacity = set->capacity;
        size_t new_capacity = old_capacity;
 
        // Note that since a valid id doesn't have its high bit set, and
        // capacity is in terms of elements, doubling the capacity won't wrap
        do {
            new_capacity *= 2;
        } while (id >= new_capacity);
 
 
        // Grow dense array
        ECS_ASSERT(ecs_is_valid_capacity(set->capacity, sizeof(ecs_entity_t)));
        set->dense = (ecs_entity_t*)ecs_realloc_zero(ecs,
                                                set->dense,
                                                old_capacity * sizeof(ecs_entity_t),
                                                new_capacity * sizeof(ecs_entity_t));
 
 
        // Grow sparse array and zero it
        ECS_ASSERT(ecs_is_valid_capacity(set->capacity, sizeof(size_t)));
        set->sparse = (size_t*)ecs_realloc_zero(ecs,
                                                set->sparse,
                                                old_capacity * sizeof(size_t),
                                                new_capacity * sizeof(size_t));
 
        // Set the new capacity
        set->capacity = new_capacity;
    }
 
    // Add ID to set
    set->dense[set->size].id = id;
    set->sparse[id] = set->size;
    set->size++;
 
    return true;
}
 
static inline bool ecs_sparse_set_find(ecs_sparse_set_t* set, ecs_id_t id, size_t* found)
{
    ECS_ASSERT(ecs_is_not_null(set));
    ECS_ASSERT(ecs_is_valid_id(id));
 
    if (id < set->capacity && set->sparse[id] < set->size && set->dense[set->sparse[id]].id == id)
    {
        if (found) *found = set->sparse[id];
        return true;
    }
    else
    {
        if (found) *found = 0;
        return false;
    }
}
 
static inline bool ecs_sparse_set_remove(ecs_sparse_set_t* set, ecs_id_t id)
{
    ECS_ASSERT(ecs_is_not_null(set));
    ECS_ASSERT(ecs_is_valid_id(id));
 
    if (!ecs_sparse_set_find(set, id, NULL))
        return false;
 
    // Swap and remove (changes order of array)
    ecs_id_t tmp = set->dense[set->size - 1].id;
    set->dense[set->sparse[id]].id = tmp;
    set->sparse[tmp] = set->sparse[id];
 
    set->size--;
 
    return true;
}
 
/*=============================================================================
 * System entity add/remove functions
 *============================================================================*/
#if ECS_MAX_COMPONENTS <= 64
 
static inline bool ecs_entity_system_test(ecs_bitset_t require_bits,
                                          ecs_bitset_t exclude_bits,
                                          ecs_bitset_t entity_bits)
{
    if (entity_bits & exclude_bits)
        return false;
 
    if ((entity_bits & require_bits) != require_bits)
        return false;
 
    return true;
}
 
#else // ECS_MAX_COMPONENTS
 
static inline bool ecs_entity_system_test(ecs_bitset_t require_bits,
                                          ecs_bitset_t exclude_bits,
                                          ecs_bitset_t entity_bits)
{
    if (!ecs_bitset_is_zero(&exclude_bits))
    {
        ecs_bitset_t overlap = ecs_bitset_and(&entity_bits, &exclude_bits);
 
        if (ecs_bitset_true(&overlap))
        {
            return false;
        }
    }
 
    ecs_bitset_t entity_and_require = ecs_bitset_and(&entity_bits, &require_bits);
    return ecs_bitset_equal(&entity_and_require, &require_bits);
}
#endif // ECS_MAX_COMPONENTS
 
static void ecs_sync_add_remove(ecs_t* ecs, ecs_id_t entity_id, ecs_id_t comp_id)
{
    // Load entity data
    ecs_entity_data_t* entity_data = &ecs->entities[entity_id];
 
    // Add or remove entity from systems
    for (ecs_id_t sys_id = 0; sys_id < ecs->system_count; sys_id++)
    {
        ecs_sys_data_t* sys_data = &ecs->systems[sys_id];
 
        // Skip systems that don't reference the changed component --
        // their match result cannot have changed
        if (!ecs_bitset_test(&sys_data->require_bits, comp_id) &&
            !ecs_bitset_test(&sys_data->exclude_bits, comp_id))
            continue;
 
        // Test to see if entity's components matches the system
        if (ecs_entity_system_test(sys_data->require_bits,
                                   sys_data->exclude_bits,
                                   entity_data->comp_bits))
        {
            // Add the entity directly to the sparse set
            if (ecs_sparse_set_add(ecs, &sys_data->entity_ids, entity_id))
            {
                if (sys_data->on_join)
                    sys_data->on_join(ecs, ecs_make_entity(entity_id), sys_data->udata);
            }
        }
        else
        {
            // Just remove the entity from the sparse set if its components
            // no longer match
            if (ecs_sparse_set_remove(&sys_data->entity_ids, entity_id))
            {
                if (sys_data->on_leave)
                    sys_data->on_leave(ecs, ecs_make_entity(entity_id), sys_data->udata);
            }
        }
    }
}
 
static void ecs_sync_destroy(ecs_t* ecs, ecs_id_t entity_id)
{
    // Remove entity from systems
    for (ecs_id_t sys_id = 0; sys_id < ecs->system_count; sys_id++)
    {
        ecs_sys_data_t* sys_data = &ecs->systems[sys_id];
 
        if (ecs_sparse_set_remove(&sys_data->entity_ids, entity_id))
        {
            if (sys_data->on_leave)
                sys_data->on_leave(ecs, ecs_make_entity(entity_id), sys_data->udata);
        }
    }
}
 
/*=============================================================================
 * ID array functions
 *============================================================================*/
 
static void ecs_id_array_init(ecs_t* ecs, ecs_id_array_t* array, size_t capacity)
{
    ECS_ASSERT(ecs_is_not_null(ecs));
    ECS_ASSERT(ecs_is_not_null(array));
 
    (void)ecs;
 
    array->size = 0;
    array->capacity = capacity;
 
    ECS_ASSERT(ecs_is_valid_capacity(capacity, sizeof(ecs_id_t)));
    array->data = (ecs_id_t*)ECS_MALLOC(capacity * sizeof(ecs_id_t), ecs->mem_ctx);
}
 
static void ecs_id_array_free(ecs_t* ecs, ecs_id_array_t* array)
{
    ECS_ASSERT(ecs_is_not_null(ecs));
    ECS_ASSERT(ecs_is_not_null(array));
 
    (void)ecs;
 
    ECS_FREE(array->data, ecs->mem_ctx);
}
 
static inline void ecs_id_array_push(ecs_t* ecs, ecs_id_array_t* array, ecs_id_t id)
{
    ECS_ASSERT(ecs_is_not_null(ecs));
    ECS_ASSERT(ecs_is_not_null(array));
    ECS_ASSERT(ecs_is_valid_id(id));
 
    (void)ecs;
 
    if (array->size == array->capacity)
    {
 
        // Note that since a valid id doesn't have its high bit set, and
        // capacity is in terms of elements, doubling the capacity won't wrap
        array->capacity *= 2;
 
        ECS_ASSERT(ecs_is_valid_capacity(array->capacity, sizeof(ecs_id_t)));
        array->data = (ecs_id_t*)ECS_REALLOC(array->data,
                                             array->capacity * sizeof(ecs_id_t),
                                             ecs->mem_ctx);
    }
 
    array->data[array->size++] = id;
}
 
static inline ecs_id_t ecs_id_array_pop(ecs_id_array_t* array)
{
    ECS_ASSERT(ecs_is_not_null(array));
    ECS_ASSERT(array->size > 0);
 
    return array->data[--array->size];
}
 
static inline size_t ecs_id_array_size(ecs_id_array_t* array)
{
    return array->size;
}
 
static void ecs_comp_blocks_init(ecs_t* ecs, ecs_comp_blocks_t* array, size_t size, size_t capacity)
{
    ECS_ASSERT(ecs_is_not_null(ecs));
    ECS_ASSERT(ecs_is_not_null(array));
 
    (void)ecs;
 
    ECS_MEMSET(array, 0, sizeof(ecs_comp_blocks_t));
 
    array->comp_size = size;
 
    size_t initial_blocks = (capacity + ECS_COMP_BLOCK_SIZE - 1) / ECS_COMP_BLOCK_SIZE;
    if (initial_blocks == 0) initial_blocks = 1;
 
    array->block_capacity = initial_blocks;
    array->block_count    = initial_blocks;
 
    ECS_ASSERT(ecs_is_valid_capacity(initial_blocks, sizeof(void*)));
    array->blocks = (void**)ECS_MALLOC(initial_blocks * sizeof(void*), ecs->mem_ctx);
 
    for (size_t i = 0; i < initial_blocks; i++)
    {
        ECS_ASSERT(ecs_is_valid_capacity(ECS_COMP_BLOCK_SIZE, size));
        array->blocks[i] = ECS_MALLOC(ECS_COMP_BLOCK_SIZE * size, ecs->mem_ctx);
        ECS_MEMSET(array->blocks[i], 0, ECS_COMP_BLOCK_SIZE * size);
    }
}
 
static void ecs_comp_blocks_free(ecs_t* ecs, ecs_comp_blocks_t* array)
{
    ECS_ASSERT(ecs_is_not_null(ecs));
    ECS_ASSERT(ecs_is_not_null(array));
 
    (void)ecs;
 
    for (size_t i = 0; i < array->block_count; i++)
    {
        ECS_FREE(array->blocks[i], ecs->mem_ctx);
    }
 
    ECS_FREE(array->blocks, ecs->mem_ctx);
}
 
static void ecs_comp_blocks_resize(ecs_t* ecs, ecs_comp_blocks_t* array, ecs_id_t id)
{
    ECS_ASSERT(ecs_is_not_null(ecs));
    ECS_ASSERT(ecs_is_not_null(array));
    ECS_ASSERT(ecs_is_valid_id(id));
 
    size_t required_block = id / ECS_COMP_BLOCK_SIZE;
 
    while (required_block >= array->block_count)
    {
        // Grow the block pointer array if necessary. This only moves pointers,
        // never the block data itself, so existing component pointers remain valid.
        if (array->block_count == array->block_capacity)
        {
            size_t old_capacity = array->block_capacity;
            size_t new_capacity = old_capacity * 2;
 
            ECS_ASSERT(ecs_is_valid_capacity(array->block_capacity, sizeof(void*)));
            array->blocks = (void**)ecs_realloc_zero(ecs,
                                                     array->blocks,
                                                     old_capacity * sizeof(void*),
                                                     new_capacity * sizeof(void*));
 
 
            array->block_capacity = new_capacity;
        }
 
        // Allocate and zero a new block
        ECS_ASSERT(ecs_is_valid_capacity(ECS_COMP_BLOCK_SIZE, array->comp_size));
        void* block = ECS_MALLOC(ECS_COMP_BLOCK_SIZE * array->comp_size, ecs->mem_ctx);
        ECS_MEMSET(block, 0, ECS_COMP_BLOCK_SIZE * array->comp_size);
        array->blocks[array->block_count++] = block;
    }
}
 
/*=============================================================================
 * Validation functions
 *============================================================================*/
#ifndef NDEBUG
static bool ecs_is_not_null(void* ptr)
{
    return NULL != ptr;
}
 
static bool ecs_is_valid_component_id(ecs_id_t id)
{
    return id < ECS_MAX_COMPONENTS;
}
 
static bool ecs_is_valid_system_id(ecs_id_t id)
{
    return id < ECS_MAX_SYSTEMS;
}
 
static bool ecs_is_valid_id(ecs_id_t id)
{
    // Ensures high bit is not set - works for any unsigned ecs_id_t
    return id == ((id << 1) >> 1);
}
 
static bool ecs_is_valid_capacity(size_t capacity, size_t elem_size)
{
    // Ensures any array allocations won't overflow a signed size_t and are
    // nonzero. This is not the most efficient implementation, but it is simple
 
    if (capacity == 0 || elem_size == 0)
    {
        return false;
    }
 
    size_t max_cap = (SIZE_MAX >> 1) / elem_size;
    return capacity <= max_cap;
}
 
static bool ecs_is_entity_ready(ecs_t* ecs, ecs_id_t entity_id)
{
    return ecs->entities[entity_id].ready;
}
 
static bool ecs_is_component_ready(ecs_t* ecs, ecs_id_t comp_id)
{
    return comp_id < ecs->comp_count;
}
 
static bool ecs_is_system_ready(ecs_t* ecs, ecs_id_t sys_id)
{
    return sys_id < ecs->system_count;
}
 
#endif // NDEBUG
 
#endif // PICO_ECS_IMPLEMENTATION
 
/*
    ----------------------------------------------------------------------------
    This software is available under two licenses (A) or (B). You may choose
    either one as you wish:
    ----------------------------------------------------------------------------
 
    (A) The zlib License
 
    Copyright (c) 2025 James McLean
 
    This software is provided 'as-is', without any express or implied warranty.
    In no event will the authors be held liable for any damages arising from the
    use of this software.
 
    Permission is granted to anyone to use this software for any purpose,
    including commercial applications, and to alter it and redistribute it
    freely, subject to the following restrictions:
 
    1. The origin of this software must not be misrepresented; you must not
    claim that you wrote the original software. If you use this software in a
    product, an acknowledgment in the product documentation would be appreciated
    but is not required.
 
    2. Altered source versions must be plainly marked as such, and must not be
    misrepresented as being the original software.
 
    3. This notice may not be removed or altered from any source distribution.
 
    ----------------------------------------------------------------------------
 
    (B) Public Domain (www.unlicense.org)
 
    This is free and unencumbered software released into the public domain.
 
    Anyone is free to copy, modify, publish, use, compile, sell, or distribute
    this software, either in source code form or as a compiled binary, for any
    purpose, commercial or non-commercial, and by any means.
 
    In jurisdictions that recognize copyright laws, the author or authors of
    this software dedicate any and all copyright interest in the software to the
    public domain. We make this dedication for the benefit of the public at
    large and to the detriment of our heirs and successors. We intend this
    dedication to be an overt act of relinquishment in perpetuity of all present
    and future rights to this software under copyright law.
 
    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
    AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
    ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
    WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
 
// EoF