From c7be8958ef7ca22287f060213ed5ba25e93fdadf Mon Sep 17 00:00:00 2001 From: Ukendio Date: Tue, 30 Jul 2024 15:41:28 +0200 Subject: [PATCH] Update docs --- docs/api/jecs.md | 2 - docs/api/query.md | 127 ++++++++++++++++++++-------------------------- docs/api/world.md | 12 +++-- 3 files changed, 63 insertions(+), 78 deletions(-) diff --git a/docs/api/jecs.md b/docs/api/jecs.md index 61a66a8b..98c6794c 100644 --- a/docs/api/jecs.md +++ b/docs/api/jecs.md @@ -11,8 +11,6 @@ jecs.World: World ### Wildcard -### z<> - ## Functions ### pair() diff --git a/docs/api/query.md b/docs/api/query.md index e7702fa4..0bb3e7e2 100644 --- a/docs/api/query.md +++ b/docs/api/query.md @@ -4,129 +4,112 @@ A World contains entities which have components. The World is queryable and can ## Functions -### new() +### with() ```luau -function World.new(): World +function query:with( + ...: Entity -- The IDs to query with +): Query ``` -Creates a new world. +Adds IDs to query with, but will not use their data. This is useful for Tags or generally just data you do not care for. Example: ::: code-group ```luau [luau] -local world = jecs.World.new() +for id, position in world:query(Position):with(Velocity) do + -- Do something +end ``` ```ts [typescript] -import { World } from "@rbxts/jecs"; - -const world = new World(); +for (const [id, position] of world.query(Position).with(Velocity)) { + // Do something +} ``` ::: -## entity() +:::info +Put the IDs inside of `world:query()` instead if you need the data. +::: + +### without() + ```luau -function World:entity(): Entity -- The new entit. +function query:without( + ...: Entity -- The IDs to filter against. +): Query -- Returns the Query ``` -Creates a new entity. +Removes entities with the provided IDs from the query. Example: ::: code-group ```luau [luau] -local entity = world:entity() +for _ in world:query(Position):without(Velocity) do + -- Do something +end ``` ```ts [typescript] -const entity = world.entity(); +for (const _ of world.query(Position).without(Velocity)) { + // Do something +} ``` -:: -: +::: + +### replace() -### component() ```luau -function World:component(): Entity -- The new componen. +function query:replace( + fn: (entity: Entity, ...: T...) -> U... -- ): () -- The callback that will transform the entities' data ``` -Creates a new component. +This function takes a callback which is given the current queried data of each matching entity. The values returned by the callback will be set as the new data for each given ID on the entity. Example: ::: code-group ```luau [luau] -local Health = world:component() :: jecs.Entity +world:query(Position, Velocity):replace(function(e, position, velocity) + return position + velocity, velocity * 0.9 +end ``` ```ts [typescript] -const Health = world.component(); -``` -::: - -::: info -You should use this when creating components. - -For example, a Health type should be created using this. -::: - -### get() -```luau -function World:get( - entity: Entity, -- The entity - ...: Entity -- The types to fetch -): ... -- Returns the component data in the same order they were passed in +world + .query(Position, Velocity) + .replace((e, position, velocity) => + $tuple(position.add(velocity), velocity.mul(0.9)), + ); ``` -Returns the data for each provided type for the corresponding entity. - -::: - -### add() -```luau -function World:add( - entity: Entity, -- The entity - id: Entity -- The component ID to add -): () -``` -Adds a component ID to the entity. - -This operation adds a single (component) id to an entity. -::: info -This function is idempotent, meaning if the entity already has the id, this operation will have no side effects. ::: -### set() +### archetypes() ```luau -function World:set( - entity: Entity, -- The entity - id: Entity, -- The component ID to set - data: T -- The data of the component's type -): () +function query:archetypes(): { Archetype } ``` -Adds or changes the entity's component. - -### query() -```luau -function World:query( - ...: Entity -- The component IDs to query with. Entities that satifies the conditions will be returned -): Query<...Entity> -- Returns the Query which gets the entity and their corresponding data when iterated -``` -Creates a [`query`](query) with the given component IDs. +Returns the matching archetypes of the query. Example: ::: code-group ```luau [luau] -for id, position, velocity in world:query(Position, Velocity) do - -- Do something +for i, archetype in world:query(Position, Velocity):archetypes() do + local field = archetype.records + local columns = archetype.columns + for row, entity in archetype.entities do + local position = columns[field[Position]][row] + local velocity = columns[field[Velocity]][row] + -- Do something + end end ``` -```ts [typescript] -for (const [id, position, velocity] of world.query(Position, Velocity) { - // Do something -} -``` +::: +:::info +This function is meant for internal usage. Use this if you want to maximize performance by inlining the iterator. ::: diff --git a/docs/api/world.md b/docs/api/world.md index e7702fa4..dd3d0a18 100644 --- a/docs/api/world.md +++ b/docs/api/world.md @@ -1,4 +1,4 @@ -# Query +# World A World contains entities which have components. The World is queryable and can be used to get entities with a specific set of components. @@ -109,10 +109,10 @@ Adds or changes the entity's component. ### query() ```luau function World:query( - ...: Entity -- The component IDs to query with. Entities that satifies the conditions will be returned -): Query<...Entity> -- Returns the Query which gets the entity and their corresponding data when iterated + ...: Entity -- The IDs to query with +): Query -- Returns the Query ``` -Creates a [`query`](query) with the given component IDs. +Creates a [`query`](query) with the given IDs. Entities that satisfies the conditions of the query will be returned and their corresponding data. Example: ::: code-group @@ -130,3 +130,7 @@ for (const [id, position, velocity] of world.query(Position, Velocity) { ``` ::: + +:::info +Queries are uncached by default, this is generally very cheap unless you have high fragmentation from e.g. relationships. +:::