Sovereignty/jecs
1
0
Fork 0
mirror of https://github.com/Ukendio/jecs.git synced 2025-04-24 17:10:03 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Improvements to "world" api documentation (#128)

Browse source 
* Improvements to "world" api documentation

I've tried to do several improvements to the api documentation by including the methods such as `delete`, `remove` and `clear` + added more extensive examples for some things

Please tell me if there's anything that needs to be corrected

* Update world.md

* Update world.md

* Update world.md

* Update world.md
This commit is contained in:
silly-spongus 2024-10-06 01:40:26 +00:00 committed by GitHub
parent 9a0a578acd
commit 106dc42128
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 288 additions and 61 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

349
docs/api/world.md
View file

@ -1,39 +1,39 @@
# 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.
A World contains entities which have components. The World is queryable and can be used to get entities with a specific set of components and to perform different kinds of operations on them.
# Functions
## new()
## new
`World` utilizes a class, meaning JECS allows you to create multiple worlds.
```luau
function World.new(): World
```
Creates a new world.
Example:
::: code-group
::: code-group
```luau [luau]
local world = jecs.World.new()
local myOtherWorld = jecs.World.new()
```
```ts [typescript]
import { World } from "@rbxts/jecs";
const world = new World();
const myOtherWorld = new World();
```
:::
## entity()
```luau
function World:entity(): Entity -- The new entit.
```
# Methods
## entity
Creates a new entity.
```luau
function World:entity(): Entity
```
Example:
::: code-group
::: code-group
```luau [luau]
local entity = world:entity()
```
@ -41,20 +41,21 @@ local entity = world:entity()
```ts [typescript]
const entity = world.entity();
```
:::
## component()
## component
Creates a new component. Do note components are entities as well, meaning JECS allows you to add other components onto them.
These are meant to be added onto other entities through `add` and `set`
```luau
function World:component<T>(): Entity<T> -- The new componen.
```
Creates a new component.
Example:
::: code-group
::: code-group
```luau [luau]
local Health = world:component() :: jecs.Entity<number>
local Health = world:component() :: jecs.Entity<number> -- Typecasting this will allow us to know what kind of data the component holds!
```
```ts [typescript]
@ -62,114 +63,340 @@ const Health = world.component<number>();
```
:::
::: info
You should use this when creating components.
For example, a Health type should be created using this.
:::
## get()
## get
Returns the data present in the component that was set in the entity. Will return nil if the component was a tag or is not present.
```luau
function World:get<T>(
entity: Entity, -- The entity
id: Entity<T> -- The component ID to fetch
): T
): T?
```
Returns the data for the component data the corresponding entity, nil if entity does not have the ID or was a tag.
## has()
Example:
::: code-group
```luau [luau]
local Health = world:component() :: jecs.Entity<number>
local Entity = world:entity()
world:set(Entity, Health, 100)
print(world:get(Entity, Health))
-- Outputs:
-- 100
```
```ts [typescript]
const Health = world.component<number>();
const Entity = world.entity();
world.set(Entity, Health, 100);
print(world.get(Entity, Health))
// Outputs:
// 100
```
:::
## has
Returns whether an entity has a component (ID). Useful for checking if an entity has a tag or if you don't care of the data that is inside the component.
```luau
function World:has(
entity: Entity, -- The entity
id: Entity<T> -- The component ID to check
): boolean
```
Returns whether the entity has the ID.
Example:
::: code-group
```luau [luau]
local IsMoving = world:component()
local Ragdolled = world:entity() -- This is a tag, meaning it won't contain data
local Health = world:component() :: jecs.Entity<number>
local Entity = world:entity()
world:set(Entity, Health, 100)
world:add(Entity, Ragdolled)
print(world:has(Entity, Health))
print(world:has(Entity, IsMoving)
print(world:get(Entity, Ragdolled))
print(world:has(Entity, Ragdolled))
-- Outputs:
-- true
-- false
-- nil
-- true
```
```ts [typescript]
const IsMoving = world.component();
const Ragdolled = world.entity(); -- This is a tag, meaning it won't contain data
const Health = world.component<number>();
const Entity = world.entity();
world.set(Entity, Health, 100);
world.add(Entity, Ragdolled);
print(world.has(Entity, Health));
print(world.has(Entity, IsMoving));
print(world.get(Entity, Ragdolled));
print(world.has(Entity, Ragdolled));
// Outputs:
// true
// false
// nil
// true
```
:::
## add()
## add
Adds a component (ID) to the entity. Useful for adding a tag to an entity, as this adds the component to the entity without any additional values inside
```luau
function World:add(
entity: Entity, -- The entity
id: Entity<T> -- The component ID to add
): ()
): void
```
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()
## set
Adds or changes data in the entity's component.
```luau
function World:set(
entity: Entity, -- The entity
id: Entity<T>, -- The component ID to set
data: T -- The data of the component's type
): ()
): void
```
Adds or changes the entity's component.
## query()
```luau
function World:query(
...: Entity -- The IDs to query with
): Query
```
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
::: code-group
```luau [luau]
for id, position, velocity in world:query(Position, Velocity) do
-- Do something
local Health = world:component() :: jecs.Entity<number>
local Entity = world:entity()
world:set(Entity, Health, 100)
print(world:get(Entity, Health))
world:set(Entity, Health, 50)
print(world:get(Entity, Health))
-- Outputs:
-- 100
-- 50
```
```ts [typescript]
const Health = world.component<number>();
const Entity = world.entity();
world.set(Entity, Health, 100);
print(world.get(Entity, Health))
world.set(Entity, Health, 50);
print(world.get(Entity, Health))
// Outputs:
// 100
// 50
```
:::
## query
Creates a [`query`](query) with the given components (IDs). Entities that satisfies the conditions of the query will be returned and their corresponding data.
```luau
function World:query(
...: Entity -- The components to query with
): Query
```
Example:
::: code-group
```luau [luau]
-- Entity could also be a component if a component also meets the requirements, since they are also entities which you can add more components onto
for entity, position, velocity in world:query(Position, Velocity) do
end
```
```ts [typescript]
for (const [id, position, velocity] of world.query(Position, Velocity) {
// Roblox-TS allows to deconstruct tuples on the act like if they were arrays!
// Entity could also be a component if a component also meets the requirements, since they are also entities which you can add more components onto
for (const [entity, position, velocity] of world.query(Position, Velocity) {
// Do something
}
```
:::
:::info
Queries are uncached by default, this is generally very cheap unless you have high fragmentation from e.g. relationships.
:::
## target()
## target
Get the target of a relationship.
This will return a target (second element of a pair) of the entity for the specified relationship. The index allows for iterating through the targets, if a single entity has multiple targets for the same relationship.
If the index is larger than the total number of instances the entity has for the relationship or if there is no pair with the specified relationship on the entity, the operation will return nil.
```luau
function World:target(
entity: Entity, -- The entity
relation: Entity, -- The relationship between the entity and the target
nth: number, -- The index
): Entity? -- The target for the relationship at the specified index.
```
Get the target of a relationship.
This will return a target (second element of a pair) of the entity for the specified relationship. The index allows for iterating through the targets, if a single entity has multiple targets for the same relationship.
If the index is larger than the total number of instances the entity has for the relationship or if there is no pair with the specified relationship on the entity, the operation will return nil.
## parent()
## parent
Get parent (target of ChildOf relationship) for entity. If there is no ChildOf relationship pair, it will return nil.
```luau
function World:parent(
child: Entity -- The child ID to find the parent of
): Entity? -- Returns the parent of the child
```
Get parent (target of ChildOf relationship) for entity. If there is no ChildOf relationship pair, it will return nil.
This operation is the same as calling:
```luau
world:target(entity, jecs.ChildOf, 0)
```
## contains
Checks if an entity or component (id) exists in the world.
```luau
function World:contains(
entity: Entity,
): boolean
```
Example:
::: code-group
```luau [luau]
local entity = world:entity()
print(world:contains(entity))
print(world:contains(1))
print(world:contains(2))
-- Outputs:
-- true
-- true
-- false
```
```ts [typescript]
const entity = world.entity();
print(world.contains(entity));
print(world.contains(1));
print(world.contains(2));
// Outputs:
// true
// true
// false
```
:::
## remove
Removes a component (ID) from an entity
```luau
function World:remove(
entity: Entity,
component: Entity<T>
): void
```
Example:
::: code-group
```luau [luau]
local IsMoving = world:component()
local entity = world:entity()
world:add(entity, IsMoving)
print(world:has(entity, IsMoving))
world:remove(entity, IsMoving)
print(world:has(entity, IsMoving))
-- Outputs:
-- true
-- false
```
```ts [typescript]
const IsMoving = world.component();
const entity = world.entity();
world.add(entity, IsMoving);
print(world.has(entity, IsMoving));
world.remove(entity, IsMoving);
print(world.has(entity, IsMoving));
// Outputs:
// true
// false
```
:::
## delete
Deletes an entity and all of its related components and relationships.
```luau
function World:delete(
entity: Entity
): void
```
Example:
::: code-group
```luau [luau]
local entity = world:entity()
print(world:has(entity))
world:delete(entity)
print(world:has(entity))
-- Outputs:
-- true
-- false
```
```ts [typescript]
const entity = world.entity();
print(world.has(entity));
world.delete(entity);
print(world.has(entity));
// Outputs:
// true
// false
```
:::
## clear
Clears all of the components and relationships of the entity without deleting it.
```luau
function World:clear(
entity: Entity
): void
```