diff --git a/libs/ecs/include/psemek/ecs/container.hpp b/libs/ecs/include/psemek/ecs/container.hpp index 19bf859b..7c8bab06 100644 --- a/libs/ecs/include/psemek/ecs/container.hpp +++ b/libs/ecs/include/psemek/ecs/container.hpp @@ -24,7 +24,10 @@ namespace psemek::ecs // TODO: // - Fully document which functions can be called from which callbacks // - Const-qualified component access + // - Negated component access + // - Constructors & destructors implementation // - Modification callbacks implementation + // - Refactor query caches // - Index API // - Index implementation @@ -36,7 +39,7 @@ namespace psemek::ecs * If any two of the passed component types are equal, the call fails with * a compilation error. * After the function returns, the new entity is considered alive (`alive(handle)` returns true). - * Creating a new entity invalidates all previously created entity accessors. + * Creating a new entity invalidates all previously created accessors. * If the entity is created during iteration (inside an `apply()` call), it is unspecified * whether the created entity will be visited by iteration or not. */ @@ -60,11 +63,11 @@ namespace psemek::ecs */ void destroy(handle const & entity); - /** Get an entity accessor for an entity, which provides access to the entity's components. + /** Get an accessor for an entity, which provides access to the entity's components. * It is designed to be a single-use object; it cannot be stored as a reference to - * the entity. Use entity_handle for that instead. + * the entity. Use handle for that instead. * Creating or destroying entities, as well as attaching or detaching components, - * invalidates all previously created entity accessors. + * invalidates all previously created accessors. * If the handle wasn't previously obtained by a `create()` call, or * the referred entity was already destroyed, the behavior is undefined. */ @@ -73,7 +76,7 @@ namespace psemek::ecs /** Attach new components to an existing entity, or update existing * components with new values. Other components of this entity * are left untouched. - * Attaching components invalidates all previously created entity accessors. + * Attaching components invalidates all previously created accessors. * For the purposes of `apply()` semantics, attaching behaves as if the * entity was destroyed and then recreated with the same handle. * If any two of the passed component types are equal, the call fails with @@ -86,7 +89,7 @@ namespace psemek::ecs /** Detach (remove) components from an existing entity. Other components of this entity * are left untouched. Detaching a component that doesn't exist does nothing. - * Detaching components invalidates all previously created entity accessors. + * Detaching components invalidates all previously created accessors. * For the purposes of `apply()` semantics, detaching behaves as if the * entity was destroyed and then recreated with the same handle. * If any two of the passed component types are equal, the call fails with @@ -106,9 +109,9 @@ namespace psemek::ecs * in unspecified order. * The function must have one of the following signatures: * void(components...) - * void(entity_handle, components...) - * void(entity_container, components...) - * void(entity_container, entity_handle, components...) + * void(handle, components...) + * void(container, components...) + * void(container, handle, components...) * The function can freely create or destroy entities, and or attach/detach * components to existing entities. It is unspecified whether the function * will or will not visit newly created entities during this `apply()` call. @@ -117,7 +120,7 @@ namespace psemek::ecs * An optional query cache can be supplied to speed up iteration. * If any two of the passed component types are equal, the call fails with * a compilation error. - * If the query cache wasn't created with the exact sequence of component + * If the query cache wasn't created with the exact same sequence of component * types, the behavior is undefined. * If the function accesses passed components after destroying the * currently visited entity, the behavior is undefined. @@ -132,16 +135,16 @@ namespace psemek::ecs * views of respective components. * The function must have one of the following signatures: * void(span...) - * void(span, span...) - * void(entity_container, span...) - * void(entity_container, span, span...) + * void(span, span...) + * void(container, span...) + * void(container, span, span...) * The size of all spans within a single function call are the same, * except for empty component types (i.e. std::is_empty_v is true), * each having an unspecified non-zero size. * An optional query cache can be supplied to speed up iteration. * If any two of the passed component types are equal, the call fails with * a compilation error. - * If the query cache wasn't created with the exact sequence of component + * If the query cache wasn't created with the exact same sequence of component * types, the behavior is undefined. * If the function creates or destroyes entities, the behavior is undefined. * If the function recursively calls `apply()` or `batch_apply()`, the behavior is undefined. @@ -156,7 +159,7 @@ namespace psemek::ecs * The constructor function must have the same signature as a function * passed to the `apply()` call. * The returned value is an ownerwhip token. Destroying it removes - * the constructor from the entity_container. + * the constructor from the container. * If any two of the passed component types are equal, the call fails with * a compilation error. * If the constructor modifies the entity's archetype (i.e. attaches or @@ -176,7 +179,7 @@ namespace psemek::ecs * The destructor function must have the same signature as a function * passed to the `apply()` call. * The returned value is an ownerwhip token. Destroying it removes - * the destructor from the entity_container. + * the destructor from the container. * If any two of the passed component types are equal, the call fails with * a compilation error. * If the destructor modifies the entity's archetype (i.e. attaches or @@ -190,7 +193,7 @@ namespace psemek::ecs /** Register a component modification callback. Each time an entity that has * the specified set of components is modified, and the modification only * affects this callback's components, the callback is called. - * If the modification occurred via an entity_accessor, the callback is called + * If the modification occurred via an accessor, the callback is called * when the accessor is destroyed, allowing for transaction-like modification. * If the modification occurred via an `apply()` or `batch_apply()` call, * the callback is called as if immediately after this call. @@ -200,12 +203,13 @@ namespace psemek::ecs * The callback must have the same signature as a function * passed to the `apply()` call. * The returned value is an ownerwhip token. Destroying it removes - * the callback from the entity_container. + * the callback from the container. * If any two of the passed component types are equal, the call fails with * a compilation error. * If the callback modifies the entity's archetype (i.e. attaches or * detaches components), or destroys the entity, the behavior is undefined. */ + // TODO: implement template registration_token watch(Function && function);