From 8194b7db2489fdd34af5e6bdd6e62ed761715f98 Mon Sep 17 00:00:00 2001 From: Ukendio Date: Sun, 18 May 2025 15:28:19 +0200 Subject: [PATCH] Update docs with new API --- docs/api/world.md | 23 ++++++++++++++--------- docs/learn/overview.md | 30 +++++++++++++++++++++++------- jecs.luau | 2 +- 3 files changed, 38 insertions(+), 17 deletions(-) diff --git a/docs/api/world.md b/docs/api/world.md index ddfaf7c..a4367c3 100644 --- a/docs/api/world.md +++ b/docs/api/world.md @@ -34,24 +34,23 @@ const myOtherWorld = new World(); ## entity -Creates a new entity. +Creates a new entity. It accepts the overload to create an entity with a specific ID. ```luau -function World:entity(): Entity +function World:entity( + id: Entity? -- The desired id +): Entity ``` Example: ::: code-group - ```luau [luau] local entity = world:entity() ``` - ```ts [typescript] const entity = world.entity(); ``` - ::: ## component @@ -464,23 +463,19 @@ function World:each( ``` Example: - ::: code-group - ```luau [luau] local id = world:entity() for entity in world:each(id) do -- Do something end ``` - ```ts [typescript] const id = world.entity(); for (const entity of world.each(id)) { // Do something } ``` - ::: ## children @@ -498,3 +493,13 @@ This is the same as calling: ```luau world:each(pair(ChildOf, parent)) ``` + +## range + +Enforces a check for entities to be created within a desired range. +```luau +function World:range( + range_begin: number -- The starting point, + range_begin: number? -- The end point (optional) +) +``` diff --git a/docs/learn/overview.md b/docs/learn/overview.md index d100b10..020c9b6 100644 --- a/docs/learn/overview.md +++ b/docs/learn/overview.md @@ -2,7 +2,7 @@ Jecs is a standalone entity-component-system module written in Luau. ECS ("entity-component-system") describes one way to write games in a more data oriented design. -# Hello World, Entity and Component +## Hello World, Entity and Component It all has to start somewhere. A world stores entities and their components, and manages them. This tour will reference it for every operation. :::code-group ```luau [luau] @@ -76,7 +76,6 @@ print(`{world:get(Position, jecs.Name)} is a Component: {world:has(Position, jec -- Output: -- Position is a Component: true ``` - ```typescript [typescript] const Position = world.component(); world.set(Position, jecs.Name, "Position") // Using regular apis to set metadata on component entities! @@ -87,6 +86,28 @@ print(`${world.get(Position, jecs.Name)} is a Component: ${world.has(Position, j ``` ::: +### Entity ranges +Jecs reserves entity ids under a threshold (HI_COMPONENT_ID, default is 256) for components. That means that regular entities will start after this number. This number can be further specified via the `range` member function. + +```luau [luau] +world:range(1000, 5000) -- Defines the lower and upper bounds of the entity range respectively + +local e = world:entity() +print(e) +-- Output: +-- 1000 +``` +```typescript [typescript] +world.range(1000, 5000) -- Defines the lower and upper bounds of the entity range respectively + +local e = world.entity() +print(e) +// Output: +// 1000 +``` +``` +::: + ### Hooks Component data generally need to adhere to a specific interface, and sometimes requires side effects to run upon certain lifetime cycles. In `jecs`, there are hooks which are `component traits`, that can define the behaviour of a component and enforce invariants, but can only be invoked through mutations on the component data. You can only configure a single `OnAdd`, `OnRemove` and `OnChange` hook per component, just like you can only have a single constructor and destructor. @@ -636,11 +657,6 @@ Relationships do not fundamentally change or extend the capabilities of the stor Because of this, adding/removing relationships to entities has the same performance as adding/removing regular components. This becomes more obvious when looking more closely at a function that adds a relationship pair. -### Id ranges -Jecs reserves entity ids under a threshold (HI_COMPONENT_ID, default is 256) for components. This low id range is used by the storage to more efficiently encode graph edges between archetypes. Graph edges for components with low ids use direct array indexing, whereas graph edges for high ids use a hashmap. Graph edges are used to find the next archetype when adding/removing component ids, and are a contributing factor to the performance overhead of add/remove operations. - -Because of the way pair IDs are encoded, a pair will never be in the low id range. This means that adding/removing a pair ID always uses a hashmap to find the next archetype. This introduces a small overhead. - ### Fragmentation Fragmentation is a property of archetype-based ECS implementations where entities are spread out over more archetypes as the number of different component combinations increases. The overhead of fragmentation is visible in two areas: - Archetype creation diff --git a/jecs.luau b/jecs.luau index f80b840..0270110 100644 --- a/jecs.luau +++ b/jecs.luau @@ -2570,7 +2570,7 @@ export type World = { range: (self: World, range_begin: number, range_end: number?) -> (), --- Creates a new entity - entity: (self: World, id: Entity?) -> Entity, + entity: (self: World, id: Entity?) -> Entity, --- Creates a new entity located in the first 256 ids. --- These should be used for static components for fast access. component: (self: World) -> Entity,