Entity-Component-System¶

Defines

BINOCLE_SYSTEM_PASSIVE_BIT¶: System bits positions.

BINOCLE_SYSTEM_FLAG_NORMAL¶: System flags.

BINOCLE_SYSTEM_FLAG_PASSIVE¶

Typedefs

typedef enum binocle_entity_signal_t binocle_entity_signal_t: A signal that can be sent to an entity.

typedef uint64_t binocle_entity_id_t¶: The entity itself, actually just an ID.

typedef uint64_t binocle_component_id_t¶: The component itself, actually just an ID.

typedef uint64_t binocle_system_id_t¶: The system itself, actually just an ID.

typedef struct binocle_sparse_integer_set_t binocle_sparse_integer_set_t¶

A sparse integer set, used to quickly lookup components.

typedef struct binocle_dense_integer_set_t binocle_dense_integer_set_t¶: A dense integer set, used to save some memory space to represent the entities in use by a system.

typedef struct binocle_component_t binocle_component_t¶: A component.

typedef struct binocle_system_t binocle_system_t¶: A system.

typedef struct binocle_ecs_t binocle_ecs_t¶: The ECS container.

Enums

enum binocle_entity_signal_t¶

A signal that can be sent to an entity.

Values:

enumerator BINOCLE_ENTITY_ADDED¶

enumerator BINOCLE_ENTITY_ENABLED¶

enumerator BINOCLE_ENTITY_DISABLED¶

enumerator BINOCLE_ENTITY_REMOVED¶

Functions

bool binocle_sparse_integer_set_insert(binocle_sparse_integer_set_t *set, uint64_t i)¶

Insert an integer in a sparse integer set.

Parameters

set – the sparse integer set
i – the integer to insert

Returns

true if the integer has been inserted

bool binocle_sparse_integer_set_remove(binocle_sparse_integer_set_t *set, uint64_t i)¶

Remove an integer from a sparse integer set.

Parameters

set – the sparse integer set
i – the integer to remove

Returns

true if the integer has been removed

bool binocle_sparse_integer_set_contains(binocle_sparse_integer_set_t *set, uint64_t i)¶

Checks if a sparse integer set contains an integer.

Parameters

set – the sparse integer set
i – the integer to check against

Returns

true if the sparse integer set contains the integer

void binocle_sparse_integer_set_clear(binocle_sparse_integer_set_t *set)¶

Clears a sparse integer set.

Parameters: set – the sparse integer set

bool binocle_sparse_integer_set_is_empty(binocle_sparse_integer_set_t *set)¶

Checks if the sparse integer set is empty.

Parameters: set – the sparse integer set
Returns: true if the sparse integer set is empty

uint64_t binocle_sparse_integer_set_pop(binocle_sparse_integer_set_t *set)¶

Pops the last element of the sparse integer set.

Parameters: set – the sparse integer set
Returns: the last element of the sparse integer set

void binocle_sparse_integer_set_free(binocle_sparse_integer_set_t *set)¶

Releases the resources allocated by the sparse integer set.

Parameters: set – the sparse integer set

int binocle_bits_set(unsigned char *bytes, unsigned int bit)¶

Sets a bit in an array of bytes given the bit position.

Parameters

bytes – the array used as a bit container
bit – the bit to set

Returns

the bit set

int binocle_bits_is_set(unsigned char *bytes, unsigned int bit)¶

Checks whether a given bit is set.

Parameters

bytes – the array used as a bit container
bit – the bit to set

Returns

true if the bit is set

int binocle_bits_clear(unsigned char *bytes, unsigned int bit)¶

Clears a given bit.

Parameters

bytes – the array used as a bit cvontainer
bit – the bit to clear

Returns

the bit that has been cleared

uint64_t binocle_dense_integer_set_insert(binocle_dense_integer_set_t *is, uint64_t i)¶

Insert an integer in a dense integer set.

Parameters

is – the dense integer set
i – the integer to insert

Returns

the inserted integer bit position

uint64_t binocle_dense_integer_set_remove(binocle_dense_integer_set_t *is, uint64_t i)¶

Remove an integer from a dense integer set.

Parameters

is – the dense integer set
i – the integer to remove

Returns

the position of the bit that has been cleared

bool binocle_dense_integer_set_contains(binocle_dense_integer_set_t *is, uint64_t i)¶

Check if a dense integer set contins an integer.

Parameters

is – the dense integer set
i – the integer to check

Returns

true if the dense integer set contains the integer

void binocle_dense_integer_set_clear(binocle_dense_integer_set_t *is)¶

Clear a dense integer set

Parameters: is – the dense integer set

int binocle_dense_integer_set_is_empty(binocle_dense_integer_set_t *is)¶

Check if a dense integer set is empty

Parameters: is – the dense integer set
Returns: true if the dense integer set is empty

void binocle_dense_integer_set_free(binocle_dense_integer_set_t *is)¶

Release all the resources allocated by a dense integer set

Parameters: is – the dense integer set

binocle_ecs_t binocle_ecs_new()¶

Creates a new instance of the ECS, leaving it in an uninitialized state While the ECS isn’t initialized you can call binocle_ecs_create_component and binocle_ecs_create_system to create the components and systems that you will need during program execution. Once done you have to call binocle_ecs_initialize to actually initialize all the data structures.

Note

Once the ECS has been initialized you can no longer define new components and systems.

Returns: a new ECS instance

bool binocle_ecs_initialize(binocle_ecs_t *ecs)¶

Initializes the data structures of the ECS.

Note

Once this function has been called you can no longer define new components or systems

Parameters: ecs – the ECS instance
Returns: true if the ECS has been initialized

bool binocle_ecs_free(binocle_ecs_t *ecs)¶

Releases the resources allocated by the ECS instance.

Parameters: ecs – the ECS instance
Returns: true if the resources have been fred

bool binocle_ecs_fix_data(binocle_ecs_t *ecs)¶

Moves all the entities that have been spawned during the processing of systems to the correct entity data array. This function is for internal use only and should never be called outside of the ECS itself.

Parameters: ecs – the ECS instance
Returns: true if everything went ok

bool binocle_ecs_create_entity(binocle_ecs_t *ecs, binocle_entity_id_t *entity_ptr)¶

Creates a new entity.

Parameters

ecs – the ECS instance
entity_ptr – a pointer to the entity id that will be assigned by this function

Returns

true if the entity has been spawned

unsigned char *binocle_ecs_get_entity_data(binocle_ecs_t *ecs, binocle_entity_id_t entity)¶

Gets the entity data for a given entity.

Parameters

ecs – the ECS instance
entity – the entity ID

Returns

a pointer to the entity’s data

bool binocle_ecs_create_component(binocle_ecs_t *ecs, const char *name, uint64_t component_size, binocle_component_id_t *component_ptr)¶

Defines and creates a new component.

Parameters

ecs – the ECS instance
name – the name of the component
component_size – the size of the data structure of the component
component_ptr – a pointer to the component’s ID. This function will write the component’s ID into that pointer once it’s been setup in the ECS

Returns

true if the component has been successfully added to the ECS

bool binocle_ecs_remove_components(binocle_ecs_t *ecs, binocle_entity_id_t entity, binocle_component_id_t component)¶

Removes all the components of a certain type from an entity.

Parameters

ecs – the ECS instance
entity – the entity ID
component – the component ID

Returns

true if all the components with that component ID have been removed from the entity

bool binocle_ecs_set_component(binocle_ecs_t *ecs, binocle_entity_id_t entity, binocle_component_id_t component, const void *data)¶

Sets a component for an entity. Adds the component to the entity.

Parameters

ecs – the ECS instance
entity – the entity ID
component – the component ID
data – a pointer to the actual component’s data structure containing all the values

Returns

true if the component has been set on the entity

bool binocle_ecs_get_component(binocle_ecs_t *ecs, binocle_entity_id_t entity, binocle_component_id_t component, void **ptr)¶

Gets a component from an entity.

Parameters

ecs – the ECS instance
entity – the entity ID
component – the component ID
ptr – a pointer to the struct that will contain the data of the component requested

Returns

true if the component has been found

void binocle_ecs_component_free(binocle_ecs_t *ecs, binocle_component_t *component)¶

Releases the resources allocated for a component.

Parameters

ecs – the ECS instance
component – the actual component structure

bool binocle_ecs_remove_component_i_internal(binocle_ecs_t *ecs, binocle_entity_id_t entity, binocle_component_id_t component, uint64_t i)¶

Removes a component from an entity (Internal use only)

Parameters

ecs – the ECS instance
entity – the entity ID
component – the component ID
i – the position of the component. Currently only 0 is accepted as we do not support multiple components of the same type on the same entity

Returns

true if the component has been removed

bool binocle_ecs_set_component_i_internal(binocle_ecs_t *ecs, binocle_entity_id_t entity, binocle_component_id_t component, uint64_t i, const void *data)¶

Sets a component on an entity (Internal use only)

Parameters

ecs – the ECS instance
entity – the entity ID
component – the component ID
i – the position of the component. Currently only 0 is accepted as we do not support multiple components of the
data – the pointer to the data structure of the component

Returns

true if the component has been set

bool binocle_ecs_get_component_internal(binocle_ecs_t *ecs, binocle_entity_id_t entity, binocle_component_id_t component, uint64_t i, void **ptr)¶

Gets a component from an entity (Internal use only)

Parameters

ecs – the ECS instance
entity – the entity ID
component – the component ID
i – the position of the component. Currently only 0 is accepted as we do not support multiple components of the
ptr – the pointer that will be filled with the actual data structure of the component

Returns

true if the component has been found

bool binocle_ecs_create_system(binocle_ecs_t *ecs, const char *name, void (*starting)(struct binocle_ecs_t*, void*), void (*process)(struct binocle_ecs_t*, void*, binocle_entity_id_t, float), void (*ending)(struct binocle_ecs_t*, void*), void (*subscribed)(struct binocle_ecs_t*, void*, binocle_entity_id_t), void (*unsubscribed)(struct binocle_ecs_t*, void*, binocle_entity_id_t), void *user_data, uint64_t flags, uint64_t *system_ptr)¶

Creates a new system.

Parameters

ecs – the ECS instance
name – the name of the system
starting – the callback that will be called once the system is starting up
process – the callback that will be called at each update of the system
ending – the callback that will be called when the system is terminated
subscribed – the callback that will be called once an entity has been subscribed to this system
unsubscribed – the callback that will be called once an entity has been unsubscribed from this system
user_data – a pointer to user data that can be stored within the system
flags – the flags that specify the kind of system. Available values: BINOCLE_SYSTEM_FLAG_NORMAL for a normal system that will be called at each update BINOCLE_SYSTEM_FLAG_PASSIVE for a system that should be manually called by the developer
system_ptr –

Returns

the pointer to the system that has just been created

bool binocle_ecs_process_system(binocle_ecs_t *ecs, binocle_system_id_t system, float delta)¶

Runs a system update.

Parameters

ecs – the ECS instance
system – the ID of the system
delta – the delta time (in seconds) since the last update

Returns

true if the system has processed its entities successfully

bool binocle_ecs_signal(binocle_ecs_t *ecs, binocle_entity_id_t entity, binocle_entity_signal_t signal)¶

Sends a signal to an entity Sending a signal sets up the values needed to let the systems process the entities.

Parameters

ecs – the ECS instance
entity – the entity ID
signal – the signal to send to the entity Available values: BINOCLE_ENTITY_ADDED the entity has just been added to the ECS BINOCLE_ENTITY_ENABLED the entity has been enabled BINOCLE_ENTITY_DISABLED the entity has been disabled BINOCLE_ENTITY_REMOVED the entity has been removed from the ECS

Returns

true if the signal has been sent successfully

bool binocle_ecs_watch(binocle_ecs_t *ecs, binocle_system_id_t system, binocle_component_id_t component)¶

Adds a component to the list of watched components of a system.

Parameters

ecs – the ECS instance
system – the system ID
component – the component ID

Returns

true if the component has been added to the watch list of the system

bool binocle_ecs_exclude(binocle_ecs_t *ecs, binocle_system_id_t system, binocle_component_id_t component)¶

Excludes a component from the list of watched components of a system.

Parameters

ecs – the ECS instance
system – the system ID
component – the component ID

Returns

true if the component has been excluded from the list of watched items of the system

void binocle_ecs_subscribe(binocle_ecs_t *ecs, binocle_system_t *system, binocle_entity_id_t entity)¶

Subscribes an entity to a system.

Parameters

ecs – the ECS instance
system – the system ID
entity – the entity ID

void binocle_ecs_unsubscribe(binocle_ecs_t *ecs, binocle_system_t *system, binocle_entity_id_t entity)¶

Unsubscribes an entity from a system.

Parameters

ecs – the ECS instance
system – the system ID
entity – the entity ID

void binocle_ecs_check(binocle_ecs_t *ecs, binocle_system_t *system, binocle_entity_id_t entity)¶

Checks if an entity should be processed by a system (Internal use only)

Parameters

ecs – the ECS instance
system – the system structure
entity – the entity id

bool binocle_ecs_process(binocle_ecs_t *ecs, float delta)¶

Updates the ECS and runs its associated systems.

Parameters

ecs – the ECS instance
delta – the delta time since the last update in seconds

Returns

true if the processing finished successfully

struct binocle_sparse_integer_set_t

#include <binocle_ecs.h>

A sparse integer set, used to quickly lookup components.