From 55f2d46af10e0ba9dfec4a86189b5e92f1efef99 Mon Sep 17 00:00:00 2001 From: herbglitch Date: Sat, 21 Jun 2025 18:24:55 -0600 Subject: [PATCH] added documentation to entity --- include/arc/std/entity.h | 55 ++++++++++++++++++++++++++++++++-------- src/std/entity.c | 4 +-- 2 files changed, 47 insertions(+), 12 deletions(-) diff --git a/include/arc/std/entity.h b/include/arc/std/entity.h index 10d9112..bd19287 100644 --- a/include/arc/std/entity.h +++ b/include/arc/std/entity.h @@ -20,7 +20,7 @@ typedef struct ARC_EntitySystem ARC_EntitySystem; typedef uint32_t ARC_Entity; /** - * @brief an entity component system type + * @brief flags to define an entities current state */ typedef enum ARC_EntityFlags { ARC_ENTITY_DEAD = 0, @@ -33,12 +33,16 @@ typedef enum ARC_EntityFlags { typedef uint32_t ARC_EntityComponent; /** - * @brief + * @brief a callback function for components attached to an entity to create an empty type when a new entity is created + * + * @param[out] type, the place to create an empty type */ typedef void (* ARC_EntityCoponent_CreateEmptyFn)(void **type); /** - * @brief + * @brief creates an empty entity system, use ARC_EntitySystem_RegisterComponent to add compenents to the entity system + * + * @parm[out] entitySystem an empty entity system */ void ARC_EntitySystem_Create(ARC_EntitySystem **entitySystem); @@ -57,37 +61,68 @@ void ARC_EntitySystem_Destroy(ARC_EntitySystem *entitySystem); * @param[in] entitySystem the entity system to register the component to * @param[in] componentSize the size of the component to register * - * @return an id for for the component + * @return a uint32_t id for for the component */ uint32_t ARC_EntitySystem_RegisterComponent(ARC_EntitySystem *entitySystem, uint32_t componentSize); /** - * @brief + * @brief inits an empty entity, usually use ARC_EntitySystem_AddComponent to add compenets to the entity this function creates + * + * @param[in] entitySystem the entitySystem to init a new entity in + * + * @return an ARC_Entity that holds the id of the newly inited slot */ ARC_Entity ARC_EntitySystem_InitEntity(ARC_EntitySystem *entitySystem); /** - * @brief + * @brief releases an entity from a given entity system + * + * @param[in] entitySystem the entity system to remove the entity from + * @param[in] entity the entity to remove */ void ARC_EntitySystem_ReleaseEntity(ARC_EntitySystem *entitySystem, ARC_Entity entity); /** - * @brief + * @brief adds a component to a given entity within an entity system + * + * @note data will be copied, so if data was created elsewere it needs to be freed elsewhere + * + * @param[in] entitySystem the entity system that holds the entity which is being modified + * @param[in] entity the entity as an id which a component is being added to + * @param[in] component the id of the compenent for the entity system + * @param[in] data the components data as a void * */ void ARC_EntitySystem_AddComponent(ARC_EntitySystem *entitySystem, ARC_Entity entity, ARC_EntityComponent component, void *data); /** - * @brief + * @brief checks if an entity has a component within an entity system + * + * @param[in] entitySystem the entity system that holds the entity which is being checked + * @param[in] entity the entity as an id + * @param[in] component the id of the compenent for the entity system + * + * @return ARC_True if the entity has the given component, otherwise ARC_False */ ARC_Bool ARC_EntitySystem_HasComponent(ARC_EntitySystem *entitySystem, ARC_Entity entity, ARC_EntityComponent component); /** - * @brief + * @brief retrieves a components data for a specific entity + * + * @param[in] entitySystem the entity system that holds the entity which is being retrieved + * + * @param[in] entity the entity as an id + * @param[in] component the id of the compenent for the entity system + * @return the components data as a void * on success, otherwise NULL */ void *ARC_EntitySystem_GetComponentData(ARC_EntitySystem *entitySystem, ARC_Entity entity, ARC_EntityComponent component); /** - * @brief + * @brief retrieves all entities which have the given components + * + * @note this function will not check for exact matches, it just returns the entitys which have all the components (the entity might have more components than what is given) + * + * @param[in] entitySystem the entity system to query entities from + * @param[in] components the components a entity has to have to match */ ARC_Array ARC_EntitySystem_QueryComponentsData(ARC_EntitySystem *entitySystem, ARC_Array components); diff --git a/src/std/entity.c b/src/std/entity.c index d83a4bd..34975bf 100644 --- a/src/std/entity.c +++ b/src/std/entity.c @@ -121,7 +121,7 @@ ARC_Entity ARC_EntitySystem_InitEntity(ARC_EntitySystem *entitySystem){ //get the next free entity ARC_Entity entity = (ARC_Entity)ARC_VectorInline_GetSize(entitySystem->data); - //TODO: check if this works + ARC_VectorInline_Add(entitySystem->data, NULL); ARC_VectorInline_Add(entitySystem->flagVector, NULL); ARC_VectorInline_Add(entitySystem->maskVector, NULL); @@ -179,7 +179,7 @@ ARC_Array ARC_EntitySystem_QueryComponentsData(ARC_EntitySystem *entitySystem, A componentsMask |= (1 << ((ARC_EntityComponent *)components.data)[index]); } - //setup teh components data and get a return size + //setup the components data and get a return size uint32_t maxEntitySize = ARC_VectorInline_GetSize(entitySystem->data) - ARC_VectorInline_GetSize(entitySystem->freeEntities); //clear the query if it already exists