lisyarus/psemek
1
0
Fork 1
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update ecs::container comments

Browse source
This commit is contained in:
Nikita Lisitsa 2023-12-16 16:38:56 +03:00
parent fa87ab4425
commit 76e43590e9
1 changed files with 22 additions and 18 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

40
libs/ecs/include/psemek/ecs/container.hpp
View file

@ -24,7 +24,10 @@ namespace psemek::ecs
// TODO: // TODO:
// - Fully document which functions can be called from which callbacks // - Fully document which functions can be called from which callbacks
// - Const-qualified component access // - Const-qualified component access
// - Negated component access
// - Constructors & destructors implementation
// - Modification callbacks implementation // - Modification callbacks implementation
// - Refactor query caches
// - Index API // - Index API
// - Index implementation // - Index implementation
@ -36,7 +39,7 @@ namespace psemek::ecs
* If any two of the passed component types are equal, the call fails with * If any two of the passed component types are equal, the call fails with
* a compilation error. * a compilation error.
* After the function returns, the new entity is considered alive (`alive(handle)` returns true). * 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 * 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. * whether the created entity will be visited by iteration or not.
*/ */
@ -60,11 +63,11 @@ namespace psemek::ecs
*/ */
void destroy(handle const & entity); 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 * 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, * 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 * If the handle wasn't previously obtained by a `create()` call, or
* the referred entity was already destroyed, the behavior is undefined. * 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 /** Attach new components to an existing entity, or update existing
* components with new values. Other components of this entity * components with new values. Other components of this entity
* are left untouched. * 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 * For the purposes of `apply()` semantics, attaching behaves as if the
* entity was destroyed and then recreated with the same handle. * entity was destroyed and then recreated with the same handle.
* If any two of the passed component types are equal, the call fails with * 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 /** Detach (remove) components from an existing entity. Other components of this entity
* are left untouched. Detaching a component that doesn't exist does nothing. * 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 * For the purposes of `apply()` semantics, detaching behaves as if the
* entity was destroyed and then recreated with the same handle. * entity was destroyed and then recreated with the same handle.
* If any two of the passed component types are equal, the call fails with * If any two of the passed component types are equal, the call fails with
@ -106,9 +109,9 @@ namespace psemek::ecs
* in unspecified order. * in unspecified order.
* The function must have one of the following signatures: * The function must have one of the following signatures:
* void(components...) * void(components...)
* void(entity_handle, components...) * void(handle, components...)
* void(entity_container, components...) * void(container, components...)
* void(entity_container, entity_handle, components...) * void(container, handle, components...)
* The function can freely create or destroy entities, and or attach/detach * The function can freely create or destroy entities, and or attach/detach
* components to existing entities. It is unspecified whether the function * components to existing entities. It is unspecified whether the function
* will or will not visit newly created entities during this `apply()` call. * 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. * 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 * If any two of the passed component types are equal, the call fails with
* a compilation error. * 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. * types, the behavior is undefined.
* If the function accesses passed components after destroying the * If the function accesses passed components after destroying the
* currently visited entity, the behavior is undefined. * currently visited entity, the behavior is undefined.
@ -132,16 +135,16 @@ namespace psemek::ecs
* views of respective components. * views of respective components.
* The function must have one of the following signatures: * The function must have one of the following signatures:
* void(span<components>...) * void(span<components>...)
* void(span<entity_handle const>, span<components>...) * void(span<handle const>, span<components>...)
* void(entity_container, span<components>...) * void(container, span<components>...)
* void(entity_container, span<entity_handle const>, span<components>...) * void(container, span<handle const>, span<components>...)
* The size of all spans within a single function call are the same, * The size of all spans within a single function call are the same,
* except for empty component types (i.e. std::is_empty_v<Component> is true), * except for empty component types (i.e. std::is_empty_v<Component> is true),
* each having an unspecified non-zero size. * each having an unspecified non-zero size.
* An optional query cache can be supplied to speed up iteration. * 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 * If any two of the passed component types are equal, the call fails with
* a compilation error. * 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. * types, the behavior is undefined.
* If the function creates or destroyes entities, 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. * 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 * The constructor function must have the same signature as a function
* passed to the `apply<Components...>()` call. * passed to the `apply<Components...>()` call.
* The returned value is an ownerwhip token. Destroying it removes * 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 * If any two of the passed component types are equal, the call fails with
* a compilation error. * a compilation error.
* If the constructor modifies the entity's archetype (i.e. attaches or * 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 * The destructor function must have the same signature as a function
* passed to the `apply<Components...>()` call. * passed to the `apply<Components...>()` call.
* The returned value is an ownerwhip token. Destroying it removes * 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 * If any two of the passed component types are equal, the call fails with
* a compilation error. * a compilation error.
* If the destructor modifies the entity's archetype (i.e. attaches or * 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 /** Register a component modification callback. Each time an entity that has
* the specified set of components is modified, and the modification only * the specified set of components is modified, and the modification only
* affects this callback's components, the callback is called. * 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. * when the accessor is destroyed, allowing for transaction-like modification.
* If the modification occurred via an `apply()` or `batch_apply()` call, * If the modification occurred via an `apply()` or `batch_apply()` call,
* the callback is called as if immediately after this 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 * The callback must have the same signature as a function
* passed to the `apply<Components...>()` call. * passed to the `apply<Components...>()` call.
* The returned value is an ownerwhip token. Destroying it removes * 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 * If any two of the passed component types are equal, the call fails with
* a compilation error. * a compilation error.
* If the callback modifies the entity's archetype (i.e. attaches or * If the callback modifies the entity's archetype (i.e. attaches or
* detaches components), or destroys the entity, the behavior is undefined. * detaches components), or destroys the entity, the behavior is undefined.
*/ */
// TODO: implement
template <typename ... Components, typename Function> template <typename ... Components, typename Function>
registration_token watch(Function && function); registration_token watch(Function && function);