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 | 203 +++++++++++++++++++++------------------------- docs/api/world.md | 12 ++- 3 files changed, 101 insertions(+), 116 deletions(-) diff --git a/docs/api/jecs.md b/docs/api/jecs.md index 61a66a8..98c6794 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 e7702fa..0bb3e7e 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() -``` - -```ts [typescript] -import { World } from "@rbxts/jecs"; - -const world = new World(); -``` - -::: - -## entity() -```luau -function World:entity(): Entity -- The new entit. -``` -Creates a new entity. - -Example: -::: code-group - -```luau [luau] -local entity = world:entity() -``` - -```ts [typescript] -const entity = world.entity(); -``` - -:: -: - -### component() -```luau -function World:component(): Entity -- The new componen. -``` -Creates a new component. - -Example: -::: code-group - -```luau [luau] -local Health = world:component() :: jecs.Entity -``` - -```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 -``` -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() -```luau -function World:set( - entity: Entity, -- The entity - id: Entity, -- The component ID to set - data: T -- The data of the component's type -): () -``` -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. - -Example: -::: code-group - -```luau [luau] -for id, position, velocity in world:query(Position, Velocity) do - -- Do something +for id, position in world:query(Position):with(Velocity) do + -- Do something end ``` ```ts [typescript] -for (const [id, position, velocity] of world.query(Position, Velocity) { +for (const [id, position] of world.query(Position).with(Velocity)) { // Do something } ``` ::: + +:::info +Put the IDs inside of `world:query()` instead if you need the data. +::: + +### without() + +```luau +function query:without( + ...: Entity -- The IDs to filter against. +): Query -- Returns the Query +``` +Removes entities with the provided IDs from the query. + +Example: +::: code-group + +```luau [luau] +for _ in world:query(Position):without(Velocity) do + -- Do something +end +``` + +```ts [typescript] +for (const _ of world.query(Position).without(Velocity)) { + // Do something +} +``` + +::: + +### replace() + +```luau +function query:replace( + fn: (entity: Entity, ...: T...) -> U... -- ): () -- The callback that will transform the entities' data +``` +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] +world:query(Position, Velocity):replace(function(e, position, velocity) + return position + velocity, velocity * 0.9 +end +``` + +```ts [typescript] +world + .query(Position, Velocity) + .replace((e, position, velocity) => + $tuple(position.add(velocity), velocity.mul(0.9)), + ); +``` + +::: + + +### archetypes() +```luau +function query:archetypes(): { Archetype } +``` +Returns the matching archetypes of the query. + +Example: +::: code-group + +```luau [luau] +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 +``` + +::: + +:::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 e7702fa..dd3d0a1 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. +:::