jecs/docs/api/world.md

# 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.

# Functions

## new()
```luau
function World.new(): World
```
Creates a new world.

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<T>(): Entity<T> -- The new componen.
```
Creates a new component.

Example:
::: code-group

```luau [luau]
local Health = world:component() :: jecs.Entity<number>
```

```ts [typescript]
const Health = world.component<number>();
```
:::

::: info
You should use this when creating components.

For example, a Health type should be created using this.
:::

## get()
```luau
function World:get<T>(
    entity: Entity, -- The entity
    id: Entity<T> -- The component ID to fetch
): T
```
Returns the data for the component data the corresponding entity, nil if entity does not have the ID or was a tag.

## has()
```luau
function World:has(
    entity: Entity, -- The entity
    id: Entity<T> -- The component ID to check
): boolean
```
Returns whether the entity has the ID.

:::

## add()
```luau
function World:add(
    entity: Entity, -- The entity
    id: Entity<T> -- 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<T>, -- 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 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

```luau [luau]
for id, position, velocity in world:query(Position, Velocity) do
	-- Do something
end
```

```ts [typescript]
for (const [id, 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()
```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()
```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)
```