diff --git a/README.md b/README.md index ce0bfe8..9e73453 100644 --- a/README.md +++ b/README.md @@ -35,6 +35,7 @@ - [Spawning Entities](#spawning-entities) - [Entity Builders](#entity-builders) - [Access Operations](#access-operations) + - [Iterating Over Fragments](#iterating-over-fragments) - [Modifying Operations](#modifying-operations) - [Debug Mode](#debug-mode) - [Queries](#queries) @@ -452,6 +453,35 @@ The [`evolved.alive`](#evolvedalive) function checks whether an entity is alive. All of these functions can be safely called on non-alive entities and non-alive fragments. Also, they do not cause any structural changes, because they do not modify anything. +### Iterating Over Fragments + +Sometimes, you may need to iterate over all fragments attached to an entity. You can use the [`evolved.each`](#evolvedeach) function for this purpose. + +```lua +local evolved = require 'evolved' + +local health = evolved.builder() + :name('health') + :spawn() + +local stamina = evolved.builder() + :name('stamina') + :spawn() + +local player = evolved.builder() + :set(health, 100) + :set(stamina, 50) + :spawn() + +for fragment, component in evolved.each(player) do + print(string.format('Fragment (%s) has value %d', + evolved.name(fragment), component)) +end +``` + +> [!NOTE] +> [Structural changes](#structural-changes) are not allowed during iteration. If you want to spawn new entities or insert/remove fragments while iterating, defer these operations until the iteration is complete. See the [Deferred Operations](#deferred-operations) section for more details. + ### Modifying Operations The library provides a classic set of functions for modifying entities. These functions are used to insert, override, and remove fragments from entities.