438 lines
14 KiB
C
438 lines
14 KiB
C
#pragma once
|
|
|
|
#include <ikarus/errors.h>
|
|
#include <ikarus/macros.h>
|
|
#include <ikarus/stdtypes.h>
|
|
|
|
/// \file entity.h
|
|
/// \author Folling <mail@folling.io>
|
|
|
|
/// \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 a number of values associated with a name or property.
|
|
///
|
|
/// 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 Flags for creating an entity.
|
|
enum IkarusEntityCreateFlags {
|
|
/// \brief No flags.
|
|
IkarusEntityCreateFlags_None = 0,
|
|
};
|
|
|
|
/// \brief Checks whether an entity exists.
|
|
/// \param entity The entity to check.
|
|
/// \pre \li Must not be null.
|
|
/// \param error_out \see errors.h
|
|
/// \return True if the entity exists, false otherwise or if an error occurs.
|
|
IKA_API bool
|
|
ikarus_entity_exists(IkarusEntity * entity, IkarusErrorData * error_out);
|
|
|
|
/// \brief Creates a new entity.
|
|
/// \param project The project to create the entity in.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param name The name of the entity.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must not be empty.
|
|
/// \param flags Flags for creating the entity.
|
|
/// \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,
|
|
IkarusEntityCreateFlags flags,
|
|
IkarusErrorData * error_out
|
|
);
|
|
|
|
/// \brief Flags for deleting an entity.
|
|
enum IkarusEntityDeleteFlags {
|
|
/// \brief No flags.
|
|
IkarusEntityDeleteFlags_None = 0,
|
|
};
|
|
|
|
/// \brief Deletes an entity and its values.
|
|
/// \param entity The entity to delete.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param flags Flags for deleting the entity.
|
|
/// \param error_out \see errors.h
|
|
IKA_API void ikarus_entity_delete(
|
|
IkarusEntity * entity,
|
|
IkarusEntityDeleteFlags flags,
|
|
IkarusErrorData * error_out
|
|
);
|
|
|
|
/// \brief Flags for copying an entity.
|
|
enum IkarusEntityCopyFlags {
|
|
/// \brief No flags.
|
|
IkarusEntityCopyFlags_None = 0,
|
|
};
|
|
|
|
/// \brief Copies an entity.
|
|
/// \param entity The entity to copy.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param flags Flags for copying the entity.
|
|
/// \param error_out \see errors.h
|
|
/// \return The copied entity or null if an error occurs.
|
|
IKA_API IkarusEntity * ikarus_entity_copy(
|
|
IkarusEntity * entity,
|
|
IkarusEntityCopyFlags flags,
|
|
IkarusErrorData * error_out
|
|
);
|
|
|
|
/// \brief Gets the project an entity belongs to.
|
|
/// \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 belongs to.
|
|
IKA_API struct IkarusProject *
|
|
ikarus_entity_get_project(IkarusEntity * 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.
|
|
IKA_API char const *
|
|
ikarus_entity_get_name(IkarusEntity * entity, IkarusErrorData * error_out);
|
|
|
|
/// \brief Flags for setting the name of an entity.
|
|
enum IkarusEntitySetNameFlags {
|
|
/// \brief No flags.
|
|
IkarusEntitySetNameFlags_None = 0,
|
|
};
|
|
|
|
/// \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.
|
|
/// \pre \li Must not be empty.
|
|
/// \param flags Flags for setting the name of the entity.
|
|
/// \param error_out \see errors.h
|
|
IKA_API void ikarus_entity_set_name(
|
|
IkarusEntity * entity,
|
|
char const * name,
|
|
IkarusEntitySetNameFlags flags,
|
|
IkarusErrorData * error_out
|
|
);
|
|
|
|
/// \brief Gets whether an entity is linked to a blueprint.
|
|
/// \param entity The entity to check the blueprint of.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param blueprint The blueprint to check the entity's link to.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \pre \li Must be in the same project as the entity.
|
|
/// \param error_out \see errors.h
|
|
/// \return True if the entity is linked to the blueprint, false otherwise or if an error occurs.
|
|
IKA_API bool ikarus_entity_is_linked_to_blueprint(
|
|
IkarusEntity * entity,
|
|
struct IkarusBlueprint * blueprint,
|
|
IkarusErrorData * error_out
|
|
);
|
|
|
|
/// \brief Gets the 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 size_out An out parameter for the number of blueprints in the returned array
|
|
/// or undefined if an error occurs.
|
|
/// \param error_out \see errors.h
|
|
IKA_API struct IkarusBlueprint ** ikarus_entity_get_linked_blueprints(
|
|
IkarusEntity * entity,
|
|
size_t * size_out,
|
|
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 linked blueprints or 0 if an error occurs.
|
|
IKA_API size_t ikarus_entity_get_linked_blueprints_count(
|
|
IkarusEntity * entity,
|
|
IkarusErrorData * error_out
|
|
);
|
|
|
|
/// \brief Flags for linking an entity to a blueprint.
|
|
enum IkarusEntityLinkBlueprintFlags {
|
|
/// \brief No flags.
|
|
IkarusEntityLinkBlueprintFlags_None = 0,
|
|
};
|
|
|
|
/// \brief Links an entity to a blueprint.
|
|
/// \details An uninitialized (default) value is created for each property of the
|
|
/// blueprint.
|
|
/// \param entity The entity to link the blueprint to.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param blueprint The blueprint to link to.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \pre \li Must be in the same project as the entity.
|
|
/// \remark If the entity is already linked to the blueprint, nothing happens.
|
|
/// \param flags Flags for linking the entity to the blueprint.
|
|
/// \param error_out \see errors.h
|
|
IKA_API void ikarus_entity_link_blueprint(
|
|
IkarusEntity * entity,
|
|
struct IkarusBlueprint * blueprint,
|
|
IkarusEntityLinkBlueprintFlags flags,
|
|
IkarusErrorData * error_out
|
|
);
|
|
|
|
/// \brief Flags for unlinking an entity from a blueprint.
|
|
enum IkarusEntityUnlinkBlueprintFlags {
|
|
/// \brief No flags.
|
|
IkarusEntityUnlinkBlueprintFlags_None = 0,
|
|
};
|
|
|
|
/// \brief Unlinks an entity from a blueprint.
|
|
/// \details All values associated with the blueprint are deleted.
|
|
/// \param entity The entity to unlink the blueprint from.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param blueprint The blueprint to unlink from.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \pre \li Must be in the same project as the entity.
|
|
/// \remark If the entity is not linked to the blueprint, nothing happens.
|
|
/// \param flags Flags for unlinking the entity from the blueprint.
|
|
/// \param error_out \see errors.h
|
|
IKA_API void ikarus_entity_unlink_blueprint(
|
|
IkarusEntity * entity,
|
|
struct IkarusBlueprint * blueprint,
|
|
IkarusEntityUnlinkBlueprintFlags flags,
|
|
IkarusErrorData * error_out
|
|
);
|
|
|
|
/// \brief Gets whether an entity has a value.
|
|
/// \param entity The entity to check the value of.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param name The value's name.
|
|
/// \pre \li Must not be null.
|
|
/// \param error_out \see errors.h
|
|
/// \return True if the entity has a value with the name, false otherwise or if an error occurs.
|
|
IKA_API bool ikarus_entity_has_value(
|
|
IkarusEntity * entity,
|
|
char const * name,
|
|
IkarusErrorData * error_out
|
|
);
|
|
|
|
/// \brief Struct for an entity value.
|
|
struct IkarusEntityValue {
|
|
/// \brief The name of the value.
|
|
char const * name;
|
|
/// \brief The value in json format. \see value.h
|
|
char const * value;
|
|
};
|
|
|
|
/// \brief Gets the values of an entity.
|
|
/// \param entity The entity to get the values of.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param size_out An out parameter for the number of values in the returned array
|
|
/// or undefined if an error occurs.
|
|
/// \param error_out \see errors.h
|
|
/// \return The values or null if an error occurs.
|
|
IKA_API IkarusEntityValue * ikarus_entity_get_values(
|
|
IkarusEntity * entity,
|
|
size_t * size_out,
|
|
IkarusErrorData * error_out
|
|
);
|
|
|
|
/// \brief Gets a 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 value's name.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param error_out \see errors.h
|
|
/// \return The value, in json format of or null if an error occurs. \see value.h
|
|
IKA_API char const * ikarus_entity_get_value(
|
|
IkarusEntity * entity,
|
|
char const * name,
|
|
IkarusErrorData * error_out
|
|
);
|
|
|
|
/// \brief Flags for setting a value of an entity.
|
|
enum IkarusEntitySetValueFlags {
|
|
/// \brief No flags.
|
|
IkarusEntitySetValueFlags_None = 0,
|
|
};
|
|
|
|
/// \brief Sets a value of an entity.
|
|
/// \details If no value exists for the name, a new one is created.
|
|
/// Any previous value is overwritten.
|
|
/// \param entity The entity to set the value of.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param name The value's name.
|
|
/// \pre \li Must not be null.
|
|
/// \param value The value to set.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must be a valid json representation of a value. \see value.h
|
|
/// \param flags Flags for setting the value.
|
|
/// \param error_out \see errors.h
|
|
IKA_API void ikarus_entity_set_value(
|
|
IkarusEntity * entity,
|
|
char const * name,
|
|
char const * value,
|
|
IkarusEntitySetValueFlags flags,
|
|
IkarusErrorData * error_out
|
|
);
|
|
|
|
/// \brief Flags for deleting a value of an entity.
|
|
enum IkarusEntityDeleteValueFlags {
|
|
/// \brief No flags.
|
|
IkarusEntityDeleteValueFlags_None = 0,
|
|
};
|
|
|
|
/// \brief Deletes a value of an entity.
|
|
/// \param entity The entity to delete the value of.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param name The property's name to delete the value of.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must be the name of a value which exists within the property.
|
|
/// \param flags Flags for deleting the value.
|
|
/// \param error_out \see errors.h
|
|
IKA_API void ikarus_entity_delete_value(
|
|
IkarusEntity * entity,
|
|
char const * name,
|
|
IkarusEntityDeleteValueFlags flags,
|
|
IkarusErrorData * error_out
|
|
);
|
|
|
|
/// \brief Gets whether an entity has a property value.
|
|
/// \param entity The entity to check the property value of.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param property The property to check the value of.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \pre \li Must be in the same project as the entity.
|
|
/// \param error_out \see errors.h
|
|
/// \return True if the entity has a value for the property, false otherwise or if an error occurs.
|
|
IKA_API bool ikarus_entity_has_property_value(
|
|
IkarusEntity * entity,
|
|
struct IkarusProperty * property,
|
|
IkarusErrorData * error_out
|
|
);
|
|
|
|
/// \brief Struct for an entity property value.
|
|
struct IkarusEntityPropertyValue {
|
|
/// \brief The property.
|
|
struct IkarusProperty * property;
|
|
/// \brief The value in json format. \see value.h
|
|
char const * value;
|
|
};
|
|
|
|
/// \brief Gets the property values of an entity.
|
|
/// \param entity The entity to get the property values of.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param size_out An out parameter for the number of property values in the
|
|
/// returned array or undefined if an error occurs.
|
|
/// \param error_out \see errors.h
|
|
/// \return The property values, or null if an error occurs.
|
|
IKA_API IkarusEntityPropertyValue * ikarus_entity_get_property_values(
|
|
IkarusEntity * entity,
|
|
size_t * size_out,
|
|
IkarusErrorData * error_out
|
|
);
|
|
|
|
/// \brief Gets the value of a property of an entity.
|
|
/// \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, in json format of or null if an error occurs. \see
|
|
/// value.h
|
|
IKA_API char const * ikarus_entity_get_property_value(
|
|
IkarusEntity * entity,
|
|
struct IkarusProperty * property,
|
|
IkarusErrorData * error_out
|
|
);
|
|
|
|
/// \brief Flags for setting the value of a property of an entity.
|
|
enum IkarusEntitySetPropertyValueFlags {
|
|
/// \brief No flags.
|
|
IkarusEntitySetPropertyValueFlags_None = 0,
|
|
};
|
|
|
|
/// \brief Sets the value of a property of an entity.
|
|
/// \details Any previous value is overwritten.
|
|
/// \param entity The entity to set the 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.
|
|
/// \pre \li Must be linked to the entity.
|
|
/// \param value The value to set.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must be a valid json representation of a value. \see value.h
|
|
/// \pre \li Must be valid for the property's schema. \see schema.h
|
|
/// \param flags Flags for setting the property value.
|
|
/// \param error_out \see errors.h
|
|
IKA_API void ikarus_entity_set_property_value(
|
|
IkarusEntity * entity,
|
|
struct IkarusProperty * property,
|
|
char const * value,
|
|
IkarusEntitySetPropertyValueFlags flags,
|
|
IkarusErrorData * error_out
|
|
);
|
|
|
|
/// \brief Flags for clearing the value of a property of an entity.
|
|
enum IkarusEntityClearPropertyValueFlags {
|
|
/// \brief No flags.
|
|
IkarusEntityClearPropertyValueFlags_None = 0,
|
|
};
|
|
|
|
/// \brief Clears the value of a property of an entity.
|
|
/// \param entity The entity to clear the value of.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param property The property to clear the value of.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \pre \li Must be linked to the entity.
|
|
/// \param flags Flags for clearing the property value.
|
|
/// \param error_out \see errors.h
|
|
IKA_API void ikarus_entity_clear_property_value(
|
|
IkarusEntity * entity,
|
|
struct IkarusProperty * property,
|
|
IkarusEntitySetPropertyValueFlags flags,
|
|
IkarusErrorData * error_out
|
|
);
|
|
|
|
IKARUS_END_HEADER
|
|
|
|
/// @}
|