318 lines
11 KiB
C
318 lines
11 KiB
C
#pragma once
|
|
|
|
#include <ikarus/errors.h>
|
|
#include <ikarus/macros.h>
|
|
#include <ikarus/stdtypes.h>
|
|
|
|
/// \file entity.h
|
|
/// \author Folling <folling@ikarus.world>
|
|
|
|
/// \defgroup entities Entities
|
|
/// \brief Entities are the core building blocks of Ikarus.
|
|
|
|
IKARUS_BEGIN_HEADER
|
|
|
|
/// \brief Entities are the core building blocks of Ikarus.
|
|
/// \details Entities store two data: A name and a set of values.
|
|
/// The name identifies the entity but does not have to be unique. The values
|
|
/// are the actual information of the entity.
|
|
///
|
|
/// For documentation on the types and layout of values \see Values.h.
|
|
///
|
|
/// Entities can be linked to blueprints.
|
|
/// The entity has a (possibly uninitialized) value for each property of all
|
|
/// blueprints it is linked to. \see Property.h \see Blueprint.h.
|
|
///
|
|
/// We distinguish between `EntityValues` and `EntityPropertyValues`.
|
|
/// `EntityValues` are a direct part of the entity.
|
|
/// `EntityPropertyValues` are an indirect part of the entity, linked to them
|
|
/// via a blueprint.
|
|
struct IkarusEntity;
|
|
|
|
/// \brief Creates an entity.
|
|
/// \param project The project the entity is part of.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param name The name of the entity.
|
|
/// \pre \li Must not be null.
|
|
/// \param error_out \see errors.h
|
|
/// \return The created entity or null if an error occurs.
|
|
IKA_API IkarusEntity * ikarus_entity_create(
|
|
struct IkarusProject * project,
|
|
char const * name,
|
|
IkarusErrorData * error_out
|
|
);
|
|
|
|
/// \brief Deletes an entity.
|
|
/// \param entity The entity to delete.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param error_out \see errors.h
|
|
/// \remark The entity must not be accessed after deletion.
|
|
IKA_API void
|
|
ikarus_entity_delete(IkarusEntity * entity, IkarusErrorData * error_out);
|
|
|
|
/// \brief Gets the id of an entity.
|
|
/// \param entity The entity to get the id of.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param error_out \see errors.h
|
|
/// \return The id of the entity or 0 if an error occurs.
|
|
IKA_API int64_t
|
|
ikarus_entity_get_id(IkarusEntity const * entity, IkarusErrorData * error_out);
|
|
|
|
/// \brief Gets the project an entity is part of.
|
|
/// \param entity The entity to get the project of.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param error_out \see errors.h
|
|
/// \return The project the entity is part of or null if an error occurs.
|
|
IKA_API IkarusProject * ikarus_entity_get_project(
|
|
IkarusEntity const * entity,
|
|
IkarusErrorData * error_out
|
|
);
|
|
|
|
/// \brief Gets the name of an entity.
|
|
/// \param entity The entity to get the name of.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param error_out \see errors.h
|
|
/// \return The name of the entity or null if an error occurs.
|
|
IKA_API char const * ikarus_entity_get_name(
|
|
IkarusEntity const * entity,
|
|
IkarusErrorData * error_out
|
|
);
|
|
|
|
/// \brief Sets the name of an entity.
|
|
/// \param entity The entity to set the name of.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param name The new name of the entity.
|
|
/// \pre \li Must not be null.
|
|
/// \param error_out \see errors.h
|
|
IKA_API void ikarus_entity_set_name(
|
|
IkarusEntity * entity,
|
|
char const * name,
|
|
IkarusErrorData * error_out
|
|
);
|
|
|
|
/// \brief Checks if an entity is linked to a blueprint.
|
|
/// \param entity The entity to check.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param blueprint The blueprint to check.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param error_out \see errors.h
|
|
/// \return True if the entity is linked to the blueprint, false otherwise.
|
|
IKA_API bool ikarus_entity_is_linked_to_blueprint(
|
|
IkarusEntity const * entity,
|
|
struct IkarusBlueprint const * blueprint,
|
|
IkarusErrorData * error_out
|
|
);
|
|
|
|
/// \brief Links an entity to a blueprint.
|
|
/// \param entity The entity to link.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param blueprint The blueprint to link the entity to.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param error_out \see errors.h
|
|
/// \remark No-op if the entity is already linked to the blueprint.
|
|
IKA_API void ikarus_entity_link_to_blueprint(
|
|
IkarusEntity * entity,
|
|
struct IkarusBlueprint * blueprint,
|
|
IkarusErrorData * error_out
|
|
);
|
|
|
|
/// \brief Unlinks an entity from a blueprint.
|
|
/// All values of the blueprints' properties will be deleted.
|
|
/// \param entity The entity to unlink.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param blueprint The blueprint to unlink the entity from.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param error_out \see errors.h
|
|
/// \remark No-op if the entity is not linked to the blueprint.
|
|
IKA_API void ikarus_entity_unlink_from_blueprint(
|
|
IkarusEntity * entity,
|
|
struct IkarusBlueprint * blueprint,
|
|
IkarusErrorData * error_out
|
|
);
|
|
|
|
/// \brief Gets all blueprints an entity is linked to.
|
|
/// \param entity The entity to get the blueprints of.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param blueprints_out The buffer to write the blueprints to.
|
|
/// \pre \li Must not be null.
|
|
/// \param blueprints_out_size The size of the buffer.
|
|
/// \param error_out \see errors.h
|
|
/// \see ikarus_entity_get_linked_blueprint_count
|
|
IKA_API void ikarus_entity_get_linked_blueprints(
|
|
IkarusEntity const * entity,
|
|
struct IkarusBlueprint ** blueprints_out,
|
|
size_t blueprints_out_size,
|
|
IkarusErrorData * error_out
|
|
);
|
|
|
|
/// \brief Gets the number of blueprints an entity is linked to.
|
|
/// \param entity The entity to get the number of linked blueprints of.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param error_out \see errors.h
|
|
/// \return The number of blueprints or undefined if an error occurs.
|
|
IKA_API size_t ikarus_entity_get_linked_blueprint_count(
|
|
IkarusEntity const * entity,
|
|
IkarusErrorData * error_out
|
|
);
|
|
|
|
/// \brief Checks if an entity has a value with a given name.
|
|
/// \param entity The entity to check.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param name The name of the value to check.
|
|
/// \pre \li Must not be null.
|
|
/// \param error_out \see errors.h
|
|
/// \return False if the entity does not have a value associated with
|
|
/// the name or if an error occurs, true otherwise.
|
|
IKA_API bool ikarus_entity_has_value(
|
|
IkarusEntity const * entity,
|
|
char const * name,
|
|
IkarusErrorData * error_out
|
|
);
|
|
|
|
/// \brief Gets the value of an entity.
|
|
/// \param entity The entity to get the value of.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param name The name of the value to get.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must be an existing value of the entity.
|
|
/// \param error_out \see errors.h
|
|
/// \return The value of the entity or null if an error occurs.
|
|
IKA_API struct IkarusValue * ikarus_entity_get_value(
|
|
IkarusEntity const * entity,
|
|
char const * name,
|
|
IkarusErrorData * error_out
|
|
);
|
|
|
|
/// \brief Sets the value of an entity.
|
|
/// If the entity does not have a value associated with the name, it is created.
|
|
/// \remark Types are overwritten if the value already exists.
|
|
/// \param entity The entity to set the value of.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param name The name of the value to set.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param value The new value of the entity.
|
|
/// \pre \li Must not be null.
|
|
/// \param error_out \see errors.h
|
|
IKA_API void ikarus_entity_set_value(
|
|
IkarusEntity * entity,
|
|
char const * name,
|
|
struct IkarusValue const * value,
|
|
IkarusErrorData * error_out
|
|
);
|
|
|
|
/// \brief Removes a value from an entity.
|
|
/// \pre \li The value must exist.
|
|
/// \param entity The entity to delete the value of.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param name The name of the value to delete.
|
|
/// \pre \li Must not be null.
|
|
/// \param error_out \see errors.h
|
|
IKA_API void ikarus_entity_remove_value(
|
|
IkarusEntity * entity,
|
|
char const * name,
|
|
IkarusErrorData * error_out
|
|
);
|
|
|
|
/// \brief Checks if a property is linked to an entity.
|
|
/// \param entity The entity to check.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param property The property to check.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param error_out \see errors.h
|
|
/// \return False if an error occurs or the entity does not have the property,
|
|
/// true otherwise.
|
|
IKA_API bool ikarus_entity_has_property(
|
|
IkarusEntity const * entity,
|
|
struct IkarusProperty const * property,
|
|
IkarusErrorData * error_out
|
|
);
|
|
|
|
/// \brief Gets the properties an entity is linked to.
|
|
/// \param entity The entity to get the linked properties of.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param properties_out The buffer to write the linked properties to.
|
|
/// \pre \li Must not be null.
|
|
/// \param error_out \see errors.h
|
|
/// \param properties_out_size The size of the buffer.
|
|
/// \see ikarus_entity_get_property_count
|
|
IKA_API void ikarus_entity_get_properties(
|
|
IkarusEntity const * entity,
|
|
struct IkarusProperty ** properties_out,
|
|
size_t properties_out_size,
|
|
IkarusErrorData * error_out
|
|
);
|
|
|
|
/// \brief Gets the number of properties an entity is linked to.
|
|
/// \param entity The entity to get the number of linked properties of.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param error_out \see errors.h
|
|
/// \return The number of properties or undefined if an error occurs.
|
|
IKA_API size_t ikarus_entity_get_property_count(
|
|
IkarusEntity const * entity,
|
|
IkarusErrorData * error_out
|
|
);
|
|
|
|
/// \brief Gets the value of a property of an entity.
|
|
/// \details If the entity has never set the value of the property,
|
|
/// the property's default value is returned.
|
|
/// \param entity The entity to get the value of.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param property The property to get the value of.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \pre \li Must be linked to the entity.
|
|
/// \param error_out \see errors.h
|
|
/// \return The value of the property or null if an error occurs.
|
|
IKA_API struct IkarusValue * ikarus_entity_get_property_value(
|
|
IkarusEntity const * entity,
|
|
struct IkarusProperty const * property,
|
|
IkarusErrorData * error_out
|
|
);
|
|
|
|
/// \brief Sets the value of a property of an entity.
|
|
/// \param entity The entity to set the property value of.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param property The property to set the value of.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param value The new value of the property.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must be of the same type as the property.
|
|
/// \pre \li Must be valid for the property's settings.
|
|
/// \param error_out \see errors.h
|
|
/// \remark If the entity does not have the property, this function fails.
|
|
IKA_API void ikarus_entity_set_property_value(
|
|
IkarusEntity * entity,
|
|
struct IkarusProperty const * property,
|
|
struct IkarusValue const * value,
|
|
IkarusErrorData * error_out
|
|
);
|
|
|
|
IKARUS_END_HEADER
|
|
|
|
// @}
|