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

Fix docs titles

Browse source
This commit is contained in:
Ukendio 2024-09-07 22:12:07 +02:00
parent 9af08c0553
commit 1067a17101
5 changed files with 360 additions and 354 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
CHANGELOG.md
View file

@ -9,6 +9,9 @@ The format is based on [Keep a Changelog][kac], and this project adheres to
[semver]: https://semver.org/spec/v2.0.0.html [semver]: https://semver.org/spec/v2.0.0.html
## [Unreleased] ## [Unreleased]
## [0.2.10] - 2024-09-07
- `[world]`: - `[world]`:
- Improved performance for hooks - Improved performance for hooks
- Changed `world:set` to be idempotent when setting tags - Changed `world:set` to be idempotent when setting tags
@ -29,6 +32,7 @@ The format is based on [Keep a Changelog][kac], and this project adheres to
- Changed `world:contains()` to return a `boolean` instead of an entity which may or may not exist - Changed `world:contains()` to return a `boolean` instead of an entity which may or may not exist
- Fixed `world:has()` to take the correct parameters - Fixed `world:has()` to take the correct parameters
## [0.2.2] - 2024-07-07 ## [0.2.2] - 2024-07-07
### Added ### Added

100
docs/api/jecs.md
View file

@ -1,50 +1,50 @@
# Jecs # Jecs
Jecs. Just an Entity Component System. Jecs. Just an Entity Component System.
## Properties # Properties
### World ## World
```luau ```luau
jecs.World: World jecs.World: World
``` ```
A world is a container of all ECS data. Games can have multiple worlds but component IDs may conflict between worlds. Ensure to register the same component IDs in the same order for each world. A world is a container of all ECS data. Games can have multiple worlds but component IDs may conflict between worlds. Ensure to register the same component IDs in the same order for each world.
### Wildcard ## Wildcard
```luau ```luau
jecs.Wildcard: Entity jecs.Wildcard: Entity
``` ```
Builtin component type. This ID is used for wildcard queries. Builtin component type. This ID is used for wildcard queries.
### Component ## Component
```luau ```luau
jecs.Component: Entity jecs.Component: Entity
``` ```
Builtin component type. Every ID created with [world:component()](world.md#component()) has this type added to it. This is meant for querying every component ID. Builtin component type. Every ID created with [world:component()](world.md#component()) has this type added to it. This is meant for querying every component ID.
### ChildOf ## ChildOf
```luau ```luau
jecs.ChildOf: Entity jecs.ChildOf: Entity
``` ```
Builtin component type. This ID is for creating parent-child hierarchies. Builtin component type. This ID is for creating parent-child hierarchies.
### Rest ## Rest
```luau ```luau
jecs.Rest: Entity jecs.Rest: Entity
``` ```
## Functions # Functions
### pair() ## pair()
```luau ```luau
function jecs.pair( function jecs.pair(
first: Entity, -- The first element of the pair, referred to as the relationship of the relationship pair. first: Entity, -- The first element of the pair, referred to as the relationship of the relationship pair.
object: Entity, -- The second element of the pair, referred to as the target of the relationship pair. object: Entity, -- The second element of the pair, referred to as the target of the relationship pair.
): number -- Returns the Id with those two elements ): number -- Returns the Id with those two elements
``` ```
::: info ::: info
Note that while relationship pairs can be used as components, meaning you can add data with it as an ID, however they cannot be used as entities. Meaning you cannot add components to a pair as the source of a binding. Note that while relationship pairs can be used as components, meaning you can add data with it as an ID, however they cannot be used as entities. Meaning you cannot add components to a pair as the source of a binding.
::: :::

262
docs/api/query.md
View file

@ -1,131 +1,131 @@
# Query # Query
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.
## Functions # Functions
### drain() ## drain()
```luau ```luau
function query:drain(): Query function query:drain(): Query
``` ```
This function will impede it from being reset when the query is being iterated. This function will impede it from being reset when the query is being iterated.
### next() ## next()
```luau ```luau
function query:next(): Query function query:next(): Query
``` ```
Get the next result in the query. Drain must have been called beforehand or otherwise it will error. Get the next result in the query. Drain must have been called beforehand or otherwise it will error.
### with() ## with()
```luau ```luau
function query:with( function query:with(
...: Entity -- The IDs to query with ...: Entity -- The IDs to query with
): Query ): Query
``` ```
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. 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: Example:
::: code-group ::: code-group
```luau [luau] ```luau [luau]
for id, position in world:query(Position):with(Velocity) do for id, position in world:query(Position):with(Velocity) do
-- Do something -- Do something
end end
``` ```
```ts [typescript] ```ts [typescript]
for (const [id, position] of world.query(Position).with(Velocity)) { for (const [id, position] of world.query(Position).with(Velocity)) {
// Do something // Do something
} }
``` ```
::: :::
:::info :::info
Put the IDs inside of `world:query()` instead if you need the data. Put the IDs inside of `world:query()` instead if you need the data.
::: :::
### without() ## without()
```luau ```luau
function query:without( function query:without(
...: Entity -- The IDs to filter against. ...: Entity -- The IDs to filter against.
): Query -- Returns the Query ): Query -- Returns the Query
``` ```
Removes entities with the provided IDs from the query. Removes entities with the provided IDs from the query.
Example: Example:
::: code-group ::: code-group
```luau [luau] ```luau [luau]
for _ in world:query(Position):without(Velocity) do for _ in world:query(Position):without(Velocity) do
-- Do something -- Do something
end end
``` ```
```ts [typescript] ```ts [typescript]
for (const _ of world.query(Position).without(Velocity)) { for (const _ of world.query(Position).without(Velocity)) {
// Do something // Do something
} }
``` ```
::: :::
### replace() ## replace()
```luau ```luau
function query:replace( function query:replace(
fn: (entity: Entity, ...: T...) -> U... -- ): () -- The callback that will transform the entities' data 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. 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: Example:
::: code-group ::: code-group
```luau [luau] ```luau [luau]
world:query(Position, Velocity):replace(function(e, position, velocity) world:query(Position, Velocity):replace(function(e, position, velocity)
return position + velocity, velocity * 0.9 return position + velocity, velocity * 0.9
end end
``` ```
```ts [typescript] ```ts [typescript]
world world
.query(Position, Velocity) .query(Position, Velocity)
.replace((e, position, velocity) => .replace((e, position, velocity) =>
$tuple(position.add(velocity), velocity.mul(0.9)), $tuple(position.add(velocity), velocity.mul(0.9)),
); );
``` ```
::: :::
### archetypes() ## archetypes()
```luau ```luau
function query.archetypes(): { Archetype } function query.archetypes(): { Archetype }
``` ```
Returns the matching archetypes of the query. Returns the matching archetypes of the query.
Example: Example:
::: code-group ::: code-group
```luau [luau] ```luau [luau]
for i, archetype in world:query(Position, Velocity).archetypes() do for i, archetype in world:query(Position, Velocity).archetypes() do
local columns = archetype.columns local columns = archetype.columns
local field = archetype.records local field = archetype.records
local P = field[Position] local P = field[Position]
local V = field[Velocity] local V = field[Velocity]
for row, entity in archetype.entities do for row, entity in archetype.entities do
local position = columns[P][row] local position = columns[P][row]
local velocity = columns[V][row] local velocity = columns[V][row]
-- Do something -- Do something
end end
end end
``` ```
::: :::
:::info :::info
This function is meant for internal usage. Use this if you want to maximize performance by inlining the iterator. This function is meant for internal usage. Use this if you want to maximize performance by inlining the iterator.
::: :::

346
docs/api/world.md
View file

@ -1,173 +1,173 @@
# World # 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.
## Functions # Functions
### new() ## new()
```luau ```luau
function World.new(): World function World.new(): World
``` ```
Creates a new world. Creates a new world.
Example: Example:
::: code-group ::: code-group
```luau [luau] ```luau [luau]
local world = jecs.World.new() local world = jecs.World.new()
``` ```
```ts [typescript] ```ts [typescript]
import { World } from "@rbxts/jecs"; import { World } from "@rbxts/jecs";
const world = new World(); const world = new World();
``` ```
::: :::
## entity() ## entity()
```luau ```luau
function World:entity(): Entity -- The new entit. function World:entity(): Entity -- The new entit.
``` ```
Creates a new entity. Creates a new entity.
Example: Example:
::: code-group ::: code-group
```luau [luau] ```luau [luau]
local entity = world:entity() local entity = world:entity()
``` ```
```ts [typescript] ```ts [typescript]
const entity = world.entity(); const entity = world.entity();
``` ```
::: :::
### component() ## component()
```luau ```luau
function World:component<T>(): Entity<T> -- The new componen. function World:component<T>(): Entity<T> -- The new componen.
``` ```
Creates a new component. Creates a new component.
Example: Example:
::: code-group ::: code-group
```luau [luau] ```luau [luau]
local Health = world:component() :: jecs.Entity<number> local Health = world:component() :: jecs.Entity<number>
``` ```
```ts [typescript] ```ts [typescript]
const Health = world.component<number>(); const Health = world.component<number>();
``` ```
::: :::
::: info ::: info
You should use this when creating components. You should use this when creating components.
For example, a Health type should be created using this. For example, a Health type should be created using this.
::: :::
### get() ## get()
```luau ```luau
function World:get<T>( function World:get<T>(
entity: Entity, -- The entity entity: Entity, -- The entity
id: Entity<T> -- The component ID to fetch 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. Returns the data for the component data the corresponding entity, nil if entity does not have the ID or was a tag.
### has() ## has()
```luau ```luau
function World:has( function World:has(
entity: Entity, -- The entity entity: Entity, -- The entity
id: Entity<T> -- The component ID to check id: Entity<T> -- The component ID to check
): boolean ): boolean
``` ```
Returns whether the entity has the ID. Returns whether the entity has the ID.
::: :::
### add() ## add()
```luau ```luau
function World:add( function World:add(
entity: Entity, -- The entity entity: Entity, -- The entity
id: Entity<T> -- The component ID to add id: Entity<T> -- The component ID to add
): () ): ()
``` ```
Adds a component ID to the entity. Adds a component ID to the entity.
This operation adds a single (component) id to an entity. This operation adds a single (component) id to an entity.
::: info ::: info
This function is idempotent, meaning if the entity already has the id, this operation will have no side effects. This function is idempotent, meaning if the entity already has the id, this operation will have no side effects.
::: :::
### set() ## set()
```luau ```luau
function World:set( function World:set(
entity: Entity, -- The entity entity: Entity, -- The entity
id: Entity<T>, -- The component ID to set id: Entity<T>, -- The component ID to set
data: T -- The data of the component's type data: T -- The data of the component's type
): () ): ()
``` ```
Adds or changes the entity's component. Adds or changes the entity's component.
### query() ## query()
```luau ```luau
function World:query( function World:query(
...: Entity -- The IDs to query with ...: Entity -- The IDs to query with
): Query ): Query
``` ```
Creates a [`query`](query) with the given IDs. Entities that satisfies the conditions of the query will be returned and their corresponding data. Creates a [`query`](query) with the given IDs. Entities that satisfies the conditions of the query will be returned and their corresponding data.
Example: Example:
::: code-group ::: code-group
```luau [luau] ```luau [luau]
for id, position, velocity in world:query(Position, Velocity) do for id, position, velocity in world:query(Position, Velocity) do
-- Do something -- Do something
end end
``` ```
```ts [typescript] ```ts [typescript]
for (const [id, position, velocity] of world.query(Position, Velocity) { for (const [id, position, velocity] of world.query(Position, Velocity) {
// Do something // Do something
} }
``` ```
::: :::
:::info :::info
Queries are uncached by default, this is generally very cheap unless you have high fragmentation from e.g. relationships. Queries are uncached by default, this is generally very cheap unless you have high fragmentation from e.g. relationships.
::: :::
### target() ## target()
```luau ```luau
function World:target( function World:target(
entity: Entity, -- The entity entity: Entity, -- The entity
relation: Entity -- The relationship between the entity and the target relation: Entity -- The relationship between the entity and the target
): Entity? -- Returns the parent of the child ): Entity? -- Returns the parent of the child
``` ```
Get the target of a relationship. Get the target of a relationship.
This will return a target (second element of a pair) of the entity for the specified relationship. This will return a target (second element of a pair) of the entity for the specified relationship.
If there is no pair with specified relationship, it will return nil. If there is no pair with specified relationship, it will return nil.
### parent() ## parent()
```luau ```luau
function World:parent( function World:parent(
child: Entity -- The child ID to find the parent of child: Entity -- The child ID to find the parent of
): Entity? -- Returns the parent of the child ): 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. 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: This operation is the same as calling:
```luau ```luau
world:target(entity, jecs.ChildOf) world:target(entity, jecs.ChildOf)
``` ```

2
src/init.luau
View file

@ -1520,8 +1520,10 @@ export type World = {
& (<A, B, C>(self: World, id: Entity, Id<A>, Id<B>, Id<C>) -> (A?, B?, C?)) & (<A, B, C>(self: World, id: Entity, Id<A>, Id<B>, Id<C>) -> (A?, B?, C?))
& <A, B, C, D>(self: World, id: Entity, Id<A>, Id<B>, Id<C>, Id<D>) -> (A?, B?, C?, D?), & <A, B, C, D>(self: World, id: Entity, Id<A>, Id<B>, Id<C>, Id<D>) -> (A?, B?, C?, D?),
--- Returns whether the entity has the ID.
has: (self: World, entity: Entity, ...Id) -> boolean, has: (self: World, entity: Entity, ...Id) -> boolean,
--- Get parent (target of ChildOf relationship) for entity. If there is no ChildOf relationship pair, it will return nil.
parent: (self: World, entity: Entity) -> Entity, parent: (self: World, entity: Entity) -> Entity,
--- Checks if the world contains the given entity --- Checks if the world contains the given entity