155 lines
6.5 KiB
C
155 lines
6.5 KiB
C
#pragma once
|
|
|
|
#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.
|
|
/// \detials Blueprints and Properties define the structure of the data.
|
|
/// Entities define the data itself.
|
|
///
|
|
/// Properties can be associated with Entities in two ways:
|
|
/// - Directly: The property is linked to the entity.
|
|
/// - Indirectly: The property is linked to a blueprint the entity is linked to.
|
|
///
|
|
/// For each property an entity is linked to, it has a value. These values depend on the property's type.
|
|
/// For more information on the types see the property documentation.
|
|
///
|
|
/// Values are the core type of data within Ikarus.
|
|
/// Each value is associated with one page and one property.
|
|
///
|
|
/// \remark Values are typed, the type of a value is specified by its associated property.
|
|
/// For more information on the types see the property documentation.
|
|
///
|
|
/// \remark Values are guaranteed to be in valid format for a given type
|
|
/// but not guaranteed to be valid under the settings of the property.
|
|
/// This is because changing the settings can invalidate existing values without resetting them.
|
|
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 parent The parent folder of the entity.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param position The position of the entity in the parent folder. \see #FolderPosition
|
|
/// \pre \li Must be within bounds for the parent folder.
|
|
/// \param name The name of the entity.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must not be empty.
|
|
/// \param blueprints Blueprints to link the entity to (0..n). Null is treated as an empty array.
|
|
/// \param blueprints_count The number of blueprints.
|
|
/// \return The created entity or null if an error occurs.
|
|
/// \remark Must be freed using #ikarus_free.
|
|
IKA_API IkarusEntity * ikarus_entity_create(
|
|
struct IkarusProject * project, char const * name, struct IkarusBlueprint ** blueprints, size_t blueprints_count
|
|
);
|
|
|
|
/// \brief Deletes an entity.
|
|
/// \param entity The entity to delete.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \remark The entity must not be accessed after deletion.
|
|
IKA_API void ikarus_entity_delete(IkarusEntity * entity);
|
|
|
|
IKA_API bool ikarus_entity_is_linked_to_blueprint(IkarusEntity const * entity, struct IkarusBlueprint const * blueprint);
|
|
|
|
/// \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.
|
|
/// \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);
|
|
|
|
/// \brief Unlinks an entity from a blueprint. All values of the properties of the blueprint the entity is linked with 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.
|
|
/// \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);
|
|
|
|
/// \brief Checks if an entity has a specific property.
|
|
/// \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.
|
|
/// \return True if the entity has the property, false otherwise.
|
|
IKA_API bool ikarus_entity_has_property(IkarusEntity const * entity, struct IkarusProperty const * property);
|
|
|
|
/// \brief Gets the number of properties of an entity.
|
|
/// \param entity The entity to get the number of properties of.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \return The number of properties or undefined if an error occurs.
|
|
IKA_API size_t ikarus_entity_get_property_count(IkarusEntity const * entity);
|
|
|
|
/// \brief Gets the properties of an entity.
|
|
/// \param entity The entity to get the properties of.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \param properties_out The buffer to write the properties to.
|
|
/// \pre \li Must not be null.
|
|
/// \param properties_out_size The size of the buffer.
|
|
IKA_API void ikarus_entity_get_properties(
|
|
IkarusEntity const * entity, struct IkarusProperty ** properties_out, size_t properties_out_size
|
|
);
|
|
|
|
/// \brief Gets the value of a property of an entity.
|
|
/// \details If the entity has never set the value of the property, the default value is returned (which may be indeterminate).
|
|
/// \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.
|
|
/// \return The value of the property or null if the entity does not have the property or an error occurs.
|
|
/// \remark Must be freed using #ikarus_free.
|
|
IKA_API struct IkarusEntityValue * ikarus_entity_get_value(IkarusEntity const * entity, struct IkarusProperty const * property);
|
|
|
|
/// \brief Sets the value of a property of an entity.
|
|
/// \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.
|
|
/// \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.
|
|
/// \remark If the entity does not have the property, this function fails.
|
|
IKA_API void ikarus_entity_set_value(
|
|
IkarusEntity * entity, struct IkarusProperty const * property, struct IkarusValue const * value
|
|
);
|
|
|
|
/// \brief Casts an entity to an object.
|
|
/// \param entity The entity to cast.
|
|
/// \pre \li Must not be null.
|
|
/// \pre \li Must exist.
|
|
/// \return The entity represented as an object or null if an error occurs.
|
|
/// \remark This operation is guaranteed to be very fast and is intended to be used frequently.
|
|
IKA_API struct IkarusObject * ikarus_entity_to_object(IkarusEntity * entity);
|
|
|
|
/// \see ikarus_entity_to_object
|
|
IKA_API struct IkarusObject const * ikarus_entity_to_object_const(IkarusEntity const * entity);
|
|
|
|
IKARUS_END_HEADER
|
|
|
|
// @}
|