Add component lifecycle diagram

SanderMertens · Jul 10, 2024 · 489b1e6 · 489b1e6
1 parent 881f28c
commit 489b1e6
Show file tree

Hide file tree

Showing 14 changed files with 18 additions and 32 deletions.
diff --git a/docs/EntitiesComponents.md b/docs/EntitiesComponents.md
@@ -980,6 +980,24 @@ Here, "has data" indicates whether a component attaches data to the entity. This
 
 A pair is a component that's composed out of two elements, such as "Likes, alice" or "Eats, apples". See the [Relationship manual](Relationships.md) for more details.
 
+### Operations
+The following table provides the base set of operations that Flecs offers for components:
+
+| Operation | Description |
+|-----------|-------------|
+| `add` | Adds component to entity. If entity already has the component, `add` does nothing. Requires that the component is default constructible. |
+| `remove` | Removes component from entity. If entity doesn't have the component, `remove` does nothing. |
+| `get` | Returns a immutable reference to the component. If the entity doesn't have the component, `get` returns `nullptr`. |
+| `get_mut` | Returns a mutable reference to the component. If the entity doesn't have the component, `get_mut` returns `nullptr`. |
+| `ensure` | Returns a mutable reference to the component. `ensure` behaves as a combination of `add` and `get_mut`. |
+| `emplace` | Returns a mutable reference to the component. If the entity doesn't have the component, `emplace` returns a reference to unconstructed memory. This enables adding components that are not default constructible. |
+| `modified` | Emits a modified event for a component. This ensures that `OnSet` observers and `on_set` hooks are invoked, and updates change detection administration. |
+| `set` | Sets the value of a component. `set` behaves as a combination of `ensure` and `modified`. `set` does not take ownership of the provided value. |
+
+The following component lifecycle diagram shows how the different operations mutate the storage and cause hooks and observers to be invoked:
+
+![Component Lifecycle](img/component_lifecycle_flow.png)
+
 ### Components are Entities
 In an ECS framework, components need to be uniquely identified. In Flecs this is done by making each component is its own unique entity. If an application has a component `Position` and `Velocity`, there will be two entities, one for each component. Component entities can be distinguished from "regular" entities as they have a `Component` component. An example:
 
@@ -1390,20 +1408,6 @@ pos.Destruct();
 </ul>
 </div>
 
-### Operations
-The following table provides the base set of operations that Flecs offers for components:
-
-| Operation | Description |
-|-----------|-------------|
-| `add` | Adds component to entity. If entity already has the component, `add` does nothing. Requires that the component is default constructible. |
-| `remove` | Removes component from entity. If entity doesn't have the component, `remove` does nothing. |
-| `get` | Returns a immutable reference to the component. If the entity doesn't have the component, `get` returns `nullptr`. |
-| `get_mut` | Returns a mutable reference to the component. If the entity doesn't have the component, `get_mut` returns `nullptr`. |
-| `ensure` | Returns a mutable reference to the component. `ensure` behaves as a combination of `add` and `get_mut`. |
-| `emplace` | Returns a mutable reference to the component. If the entity doesn't have the component, `emplace` returns a reference to unconstructed memory. This enables adding components that are not default constructible. |
-| `modified` | Emits a modified event for a component. This ensures that `OnSet` observers and `on_set` hooks are invoked, and updates change detection administration. |
-| `set` | Sets the value of a component. `set` behaves as a combination of `ensure` and `modified`. `set` does not take ownership of the provided value. |
-
 ### Singletons
 Singletons are components for which only a single instance exists on the world. They can be accessed on the world directly and do not require providing an entity. Singletons are useful for global game resources, such as game state, a handle to a physics engine or a network socket. An example:
 

diff --git a/docs/Manual.md b/docs/Manual.md
@@ -23,24 +23,6 @@ Flecs is used with other frameworks and game engines, and as such not all of its
 ### 6. Have fun!
 There are few things as satisfying as building games. If nothing else, Flecs has been built to enable creative visions both big and small. I'm having a lot of fun building Flecs, I hope you will have fun using it, and that your users will have fun playing your games :)
 
-## Diagrams
-
-### High level architecture
-This diagram provides an overview of how entities, components, tables, queries, filters and systems are wired together.
-![Architecture diagram](img/flecs-architecture-overview.png)
-
-### Component add flow
-This diagram provides an overview of the different steps that occur when adding a component to an entity. The diagram shows when component lifecycle callbacks, OnAdd triggers, OnSet systems, UnSet systems and monitors are invoked. Additionally the diagram shows how the defer mechanism is integrated with the listed Flecs operations.
-![Component add flow](img/flecs-add-component-flow.png)
-
-### Component remove flow
-This diagram provides an overview of the different steps that occur when removing a component from an entity. The diagram shows when component lifecycle callbacks, OnRemove triggers, OnSet systems, UnSet systems and monitors are invoked. Additionally the diagram shows how the defer mechanism is integrated with the listed Flecs operations.
-![Component remove flow](img/flecs-remove-component-flow.png)
-
-### Staging flow
-This diagram provides an overview of what happens when an application uses staging. Staging is a lockless mechanism that lets threads concurrently read & perform structural changes on the store. Changes are temporarily stored in a command queue per stage, which can be merged with the store when convenient.
-![Staging flow](img/flecs-staging-flow.png)
-
 ## API design
 
 ### Naming conventions

diff --git a/docs/img/component_lifecycle_flow.png b/docs/img/component_lifecycle_flow.png
diff --git a/docs/img/explorer-arguments.png b/docs/img/explorer-arguments.png
diff --git a/docs/img/explorer-query.png b/docs/img/explorer-query.png
diff --git a/docs/img/explorer-remote.png b/docs/img/explorer-remote.png
diff --git a/docs/img/explorer-rules.png b/docs/img/explorer-rules.png
diff --git a/docs/img/explorer-system.png b/docs/img/explorer-system.png
diff --git a/docs/img/flecs-add-component-flow.png b/docs/img/flecs-add-component-flow.png
diff --git a/docs/img/flecs-architecture-overview.png b/docs/img/flecs-architecture-overview.png
diff --git a/docs/img/flecs-remove-component-flow.png b/docs/img/flecs-remove-component-flow.png
diff --git a/docs/img/flecs-staging-flow.png b/docs/img/flecs-staging-flow.png
diff --git a/docs/img/query_instancing.png b/docs/img/query_instancing.png
diff --git a/docs/img/relationship_traversal.png b/docs/img/relationship_traversal.png