manual wip

MANUAL.md

@@ -0,0 +1,125 @@
+# Manual
+
+## Identifiers
+
+Identifier is a packed 40-bit integer number. The first 20 bits are the index, and the last 20 bits are the version. To create a new identifier, use the `evolved.id` function.
+
+```lua
+---@param count? integer
+---@return evolved.id ... ids
+function evolved.id(count) end
+```
+
+The `count` parameter is optional and defaults to `1`. The function returns one or more identifiers, depending on the `count` parameter. Maximum number of alive identifiers is `2^20-1` (1048575). After that, the function will throw an error `"| evolved.lua | id index overflow"`.
+
+Identifiers can be recycled. When an identifier is no longer needed, use the `evolved.destroy` function to destroy it. This will free up the identifier for reuse.
+
+```lua
+---@param ... evolved.id ids
+function evolved.destroy(...) end
+```
+
+The `destroy` function takes one or more identifiers as arguments. Destroyed identifiers will be added to the recycler free list. It is safe to destroy identifiers that are not alive (the function will just ignore them).
+
+After destroying an identifier, it can be reused by calling the `evolved.id` function again. The new identifier will have the same index as the destroyed one, but a different version. The version is incremented each time an identifier is destroyed. This mechanism allows us to reuse indices and know if an identifier is alive or not.
+
+The `evolved.alive` function set can be used to check if identifiers are alive or not.
+
+```lua
+---@param id evolved.id
+---@return boolean
+function evolved.alive(id) end
+
+---@param ... evolved.id ids
+---@return boolean
+function evolved.alive_all(...) end
+
+---@param ... evolved.id ids
+---@return boolean
+function evolved.alive_any(...) end
+```
+
+Sometimes (for debugging purposes for example), it is necessary to extract the index and version from an identifier (or pack them back). The `evolved.pack` and `evolved.unpack` functions can be used for this purpose.
+
+```lua
+---@param index integer
+---@param version integer
+---@return evolved.id id
+function evolved.pack(index, version) end
+
+---@param id evolved.id
+---@return integer index
+---@return integer version
+function evolved.unpack(id) end
+```
+
+Here is an little example of how to use identifiers:
+
+```lua
+local evolved = require 'evolved'
+
+local id = evolved.id() -- create a new identifier
+assert(evolved.alive(id)) -- check if the identifier is alive
+
+local index, version = evolved.unpack(id) -- unpack the identifier
+assert(evolved.pack(index, version) == id) -- pack it back
+
+evolved.destroy(id) -- destroy the identifier
+assert(not evolved.alive(id)) -- check if the identifier is not alive now
+```
+
+## Entities, Fragments, and Components
+
+First of all, we need to understand that entities and fragments are just identifiers. The differences between them are purely semantic. Entities are used to represent objects in the world, while fragments are used to represent types of components that can be attached to entities. Components, in the other hand, are any data that is attached to entities through fragments.
+
+Here is a simple example of how to attach a component to an entity:
+
+```lua
+local evolved = require 'evolved'
+
+local entity, fragment = evolved.id(2)
+
+evolved.set(entity, fragment, 100)
+assert(evolved.get(entity, fragment) == 100)
+```
+
+Yeah, I know, it's not very clear yet. But don't worry, we'll get there. In the next example, I'm going to name the entity and fragment, so it will be easier to understand what's going on here.
+
+```lua
+local evolved = require 'evolved'
+
+local player = evolved.id()
+
+local health = evolved.id()
+local stamina = evolved.id()
+
+evolved.set(player, health, 100)
+evolved.set(player, stamina, 50)
+
+assert(evolved.get(player, health) == 100)
+assert(evolved.get(player, stamina) == 50)
+```
+
+We have created an entity called `player` and two fragments called `health` and `stamina`. We have attached the components `100` and `50` to the entity through our fragments. After that, we can retrieve the components using the `evolved.get` function.
+
+We'll cover the `evolved.set` and `evolved.get` functions in more detail later in the section about modifying operations. For now, let's just say that they are used to setting and getting components from entities through fragments.
+
+The main thing to understand here is that we can attach any data to any identifiers using another identifiers. And yes, since fragments are just identifiers, we can use them as entities too! This very useful for marking fragments with some metadata, for example.
+
+```lua
+local evolved = require 'evolved'
+
+local serializable = evolved.id()
+
+local position = evolved.id()
+evolved.set(position, serializable, true)
+
+local velocity = evolved.id()
+evolved.set(velocity, serializable, true)
+
+local player = evolved.id()
+evolved.set(player, position, {x = 0, y = 0})
+evolved.set(player, velocity, {x = 0, y = 0})
+```
+
+In this example, we have created a fragment called `serializable` and marked the fragments `position` and `velocity` as serializable. After that, we can write a function that will serialize entities. And this function will serialize only fragments that are marked as serializable. This is a very powerful feature of the library, and it allows us to create very flexible systems. Btw, fragments of fragments are usually called `traits`.