Update documentation

* Add tests for entity-child relationships and removal in world queries, fixed world_each

* Correct test case

---------

Co-authored-by: Marcus <ukendio@gmail.com>

.github/workflows/analysis.yaml

@@ -1,19 +1,19 @@
-name: Analysis
+name: analysis
 
 on: [push, pull_request, workflow_dispatch]
 
 jobs:
-  run:
+    run:
-    name: Run Luau Analyze
+        name: Run Luau Analyze
-    runs-on: ubuntu-latest
+        runs-on: ubuntu-latest
 
-    steps:
+        steps:
-      - name: Checkout Project
+            - name: Checkout Project
-        uses: actions/checkout@v4
+              uses: actions/checkout@v4
 
-      - name: Install Luau
+            - name: Install Luau
-        uses: encodedvenom/install-luau@v2.1
+              uses: encodedvenom/install-luau@v2.1
 
-      - name: Analyze
+            - name: Analyze
-        run: |
+              run: |
-          output=$(luau-analyze src || true) # Suppress errors for now.
+                  output=$(luau-analyze src || true) # Suppress errors for now.

.github/workflows/deploy-docs.yaml

@@ -1,64 +1,64 @@
 # Sample workflow for building and deploying a VitePress site to GitHub Pages
 #
-name: Deploy VitePress site to Pages
+name: deploy-docs
 
 on:
-  # Runs on pushes targeting the `main` branch. Change this to `master` if you're
+    # Runs on pushes targeting the `main` branch. Change this to `master` if you're
-  # using the `master` branch as the default branch.
+    # using the `master` branch as the default branch.
-  push:
+    push:
-    branches: [main]
+        branches: [main]
 
-  # Allows you to run this workflow manually from the Actions tab
+    # Allows you to run this workflow manually from the Actions tab
-  workflow_dispatch:
+    workflow_dispatch:
 
 # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
 permissions:
-  contents: read
+    contents: read
-  pages: write
+    pages: write
-  id-token: write
+    id-token: write
 
 # Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
 # However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
 concurrency:
-  group: pages
+    group: pages
-  cancel-in-progress: false
+    cancel-in-progress: false
 
 jobs:
-  # Build job
+    # Build job
-  build:
+    build:
-    runs-on: ubuntu-latest
+        runs-on: ubuntu-latest
-    steps:
+        steps:
-      - name: Checkout
+            - name: Checkout
-        uses: actions/checkout@v4
+              uses: actions/checkout@v4
-        with:
+              with:
-          fetch-depth: 0 # Not needed if lastUpdated is not enabled
+                  fetch-depth: 0 # Not needed if lastUpdated is not enabled
-      # - uses: pnpm/action-setup@v3 # Uncomment this if you're using pnpm
+            # - uses: pnpm/action-setup@v3 # Uncomment this if you're using pnpm
-      # - uses: oven-sh/setup-bun@v1 # Uncomment this if you're using Bun
+            # - uses: oven-sh/setup-bun@v1 # Uncomment this if you're using Bun
-      - name: Setup Node
+            - name: Setup Node
-        uses: actions/setup-node@v4
+              uses: actions/setup-node@v4
-        with:
+              with:
-          node-version: 20
+                  node-version: 20
-          cache: npm # or pnpm / yarn
+                  cache: npm # or pnpm / yarn
-      - name: Setup Pages
+            - name: Setup Pages
-        uses: actions/configure-pages@v4
+              uses: actions/configure-pages@v4
-      - name: Install dependencies
+            - name: Install dependencies
-        run: npm ci # or pnpm install / yarn install / bun install
+              run: npm ci # or pnpm install / yarn install / bun install
-      - name: Build with VitePress
+            - name: Build with VitePress
-        run: npm run docs:build # or pnpm docs:build / yarn docs:build / bun run docs:build
+              run: npm run docs:build # or pnpm docs:build / yarn docs:build / bun run docs:build
-      - name: Upload artifact
+            - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
+              uses: actions/upload-pages-artifact@v3
-        with:
+              with:
-          path: docs/.vitepress/dist
+                  path: docs/.vitepress/dist
 
-  # Deployment job
+    # Deployment job
-  deploy:
+    deploy:
-    environment:
+        environment:
-      name: github-pages
+            name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
+            url: ${{ steps.deployment.outputs.page_url }}
-    needs: build
+        needs: build
-    runs-on: ubuntu-latest
+        runs-on: ubuntu-latest
-    name: Deploy
+        name: Deploy
-    steps:
+        steps:
-      - name: Deploy to GitHub Pages
+            - name: Deploy to GitHub Pages
-        id: deployment
+              id: deployment
-        uses: actions/deploy-pages@v4
+              uses: actions/deploy-pages@v4

.github/workflows/publish-npm.yml

@@ -1,17 +1,17 @@
-name: Publish to NPM
+name: publish-npm
 
 on:
-  push:
+    push:
-    branches: main
+        branches: [main]
 
 jobs:
-  publish:
+    publish:
-    runs-on: ubuntu-latest
+        runs-on: ubuntu-latest
-    steps:
+        steps:
-      - uses: actions/checkout@v4
+            - uses: actions/checkout@v4
-      - uses: actions/setup-node@v3
+            - uses: actions/setup-node@v3
-        with:
+              with:
-          node-version: "20"
+                  node-version: "20"
-      - uses: JS-DevTools/npm-publish@v3
+            - uses: JS-DevTools/npm-publish@v3
-        with:
+              with:
-          token: ${{ secrets.NPM_AUTH_TOKEN }}
+                  token: ${{ secrets.NPM_AUTH_TOKEN }}

.github/workflows/release.yaml

@@ -1,71 +1,71 @@
-name: Release
+name: release
 
 on:
-  push:
+    push:
-    tags: ["v*"]
+        tags: ["v*"]
 
 jobs:
-  build:
+    build:
-    name: Build
+        name: Build
-    runs-on: ubuntu-latest
+        runs-on: ubuntu-latest
-    steps:
+        steps:
-      - name: Checkout Project
+            - name: Checkout Project
-        uses: actions/checkout@v4
+              uses: actions/checkout@v4
 
-      - name: Install Rokit
+            - name: Install Rokit
-        uses: CompeyDev/setup-rokit@v0.1.2
+              uses: CompeyDev/setup-rokit@v0.1.2
 
-      - name: Install Dependencies
+            - name: Install Dependencies
-        run: wally install
+              run: wally install
 
-      - name: Build
+            - name: Build
-        run: rojo build --output build.rbxm default.project.json
+              run: rojo build --output build.rbxm default.project.json
 
-      - name: Upload Build Artifact
+            - name: Upload Build Artifact
-        uses: actions/upload-artifact@v3
+              uses: actions/upload-artifact@v3
-        with:
+              with:
-          name: build
+                  name: build
-          path: build.rbxm
+                  path: build.rbxm
 
-  release:
+    release:
-    name: Release
+        name: Release
-    needs: [build]
+        needs: [build]
-    runs-on: ubuntu-latest
+        runs-on: ubuntu-latest
-    permissions:
+        permissions:
-      contents: write
+            contents: write
-    steps:
+        steps:
-      - name: Checkout Project
+            - name: Checkout Project
-        uses: actions/checkout@v4
+              uses: actions/checkout@v4
 
-      - name: Download Jecs Build
+            - name: Download Jecs Build
-        uses: actions/download-artifact@v3
+              uses: actions/download-artifact@v3
-        with:
+              with:
-          name: build
+                  name: build
-          path: build
+                  path: build
 
-      - name: Rename Build
+            - name: Rename Build
-        run: mv build/build.rbxm jecs.rbxm
+              run: mv build/build.rbxm jecs.rbxm
 
-      - name: Create Release
+            - name: Create Release
-        uses: softprops/action-gh-release@v1
+              uses: softprops/action-gh-release@v1
-        with:
+              with:
-          name: Jecs ${{ github.ref_name }}
+                  name: Jecs ${{ github.ref_name }}
-          files: |
+                  files: |
-            jecs.rbxm
+                      jecs.rbxm
 
-  publish:
+    publish:
-    name: Publish
+        name: Publish
-    needs: [release]
+        needs: [release]
-    runs-on: ubuntu-latest
+        runs-on: ubuntu-latest
-    steps:
+        steps:
-      - name: Checkout Project
+            - name: Checkout Project
-        uses: actions/checkout@v4
+              uses: actions/checkout@v4
 
-      - name: Install Rokit
+            - name: Install Rokit
-        uses: CompeyDev/setup-rokit@v0.1.2
+              uses: CompeyDev/setup-rokit@v0.1.2
 
-      - name: Wally Login
+            - name: Wally Login
-        run: wally login --token ${{ secrets.WALLY_AUTH_TOKEN }}
+              run: wally login --token ${{ secrets.WALLY_AUTH_TOKEN }}
 
-      - name: Publish
+            - name: Publish
-        run: wally publish
+              run: wally publish

.github/workflows/unit-testing.yaml

@@ -1,31 +1,31 @@
-name: Unit Testing
+name: unit-testing
 
 on: [push, pull_request, workflow_dispatch]
 
 jobs:
-  run:
+    run:
-    name: Run Luau Tests
+        name: Run Luau Tests
-    runs-on: ubuntu-latest
+        runs-on: ubuntu-latest
-    timeout-minutes: 2
+        timeout-minutes: 2
 
-    steps:
+        steps:
-      - name: Checkout Project
+            - name: Checkout Project
-        uses: actions/checkout@v4
+              uses: actions/checkout@v4
 
-      - name: Install Luau
+            - name: Install Luau
-        uses: encodedvenom/install-luau@v4.3
+              uses: encodedvenom/install-luau@v4.3
-        with:
+              with:
-          version: 'latest'
+                  version: "latest"
-          verbose: 'true'
+                  verbose: "true"
 
-      - name: Run Unit Tests
+            - name: Run Unit Tests
-        id: run_tests
+              id: run_tests
-        run: |
+              run: |
-          output=$(luau test/tests.luau)
+                  output=$(luau test/tests.luau)
-          echo "$output"
+                  echo "$output"
-          if [[ "$output" == *"0 fails"* ]]; then
+                  if [[ "$output" == *"0 fails"* ]]; then
-            echo "Unit Tests Passed"
+                    echo "Unit Tests Passed"
-          else
+                  else
-            echo "Error: One or More Unit Tests Failed."
+                    echo "Error: One or More Unit Tests Failed."
-            exit 1
+                    exit 1
-          fi
+                  fi

docs/api/query.md

@@ -4,11 +4,20 @@ A World contains entities which have components. The World is queryable and can
 
 # Methods
 
+## iter
+
+Returns an iterator that can be used to iterate over the query.
+
+```luau
+function Query:iter(): () -> (Entity, ...)
+```
+
 ## with
+
 Adds components (IDs) to query with, but will not use their data. This is useful for Tags or generally just data you do not care for.
 
 ```luau
-function query:with(
+function Query:with(
     ...: Entity -- The IDs to query with
 ): Query
 ```
@@ -24,7 +33,7 @@ end
 
 ```ts [typescript]
 for (const [id, position] of world.query(Position).with(Velocity)) {
-    // Do something
+	// Do something
 }
 ```
 
@@ -35,10 +44,11 @@ Put the IDs inside of `world:query()` instead if you need the data.
 :::
 
 ## without
+
 Removes entities with the provided components from the query.
 
 ```luau
-function query:without(
+function Query:without(
     ...: Entity -- The IDs to filter against.
 ): Query -- Returns the Query
 ```
@@ -46,6 +56,7 @@ function query:without(
 Example:
 
 ::: code-group
+
 ```luau [luau]
 for entity, position in world:query(Position):without(Velocity) do
     -- Do something
@@ -54,15 +65,18 @@ end
 
 ```ts [typescript]
 for (const [entity, position] of world.query(Position).without(Velocity)) {
-    // Do something
+	// Do something
 }
 ```
+
 :::
 
 ## archetypes
+
 Returns the matching archetypes of the query.
+
 ```luau
-function query:archetypes(): { Archetype }
+function Query:archetypes(): { Archetype }
 ```
 
 Example:
@@ -86,3 +100,11 @@ end
 :::info
 This function is meant for people who want to really customize their query behaviour at the archetype-level
 :::
+
+## cached
+
+Returns a cached version of the query. This is useful if you want to iterate over the same query multiple times.
+
+```luau
+function Query:cached(): Query -- Returns the cached Query
+```

docs/api/world.md

@@ -1,9 +1,13 @@
 # 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 and to perform different kinds of operations on them.
 
 # Functions
+
 ## new
+
 `World` utilizes a class, meaning JECS allows you to create multiple worlds.
+
 ```luau
 function World.new(): World
 ```
@@ -11,6 +15,7 @@ function World.new(): World
 Example:
 
 ::: code-group
+
 ```luau [luau]
 local world = jecs.World.new()
 local myOtherWorld = jecs.World.new()
@@ -22,11 +27,15 @@ import { World } from "@rbxts/jecs";
 const world = new World();
 const myOtherWorld = new World();
 ```
+
 :::
 
 # Methods
+
 ## entity
+
 Creates a new entity.
+
 ```luau
 function World:entity(): Entity
 ```
@@ -34,6 +43,7 @@ function World:entity(): Entity
 Example:
 
 ::: code-group
+
 ```luau [luau]
 local entity = world:entity()
 ```
@@ -41,12 +51,15 @@ local entity = world:entity()
 ```ts [typescript]
 const entity = world.entity();
 ```
+
 :::
 
 ## 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.
 ```
@@ -54,6 +67,7 @@ function World:component<T>(): Entity<T> -- The new componen.
 Example:
 
 ::: code-group
+
 ```luau [luau]
 local Health = world:component() :: jecs.Entity<number> -- Typecasting this will allow us to know what kind of data the component holds!
 ```
@@ -61,10 +75,13 @@ local Health = world:component() :: jecs.Entity<number> -- Typecasting this will
 ```ts [typescript]
 const Health = world.component<number>();
 ```
+
 :::
 
 ## 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
@@ -75,6 +92,7 @@ function World:get<T>(
 Example:
 
 ::: code-group
+
 ```luau [luau]
 local Health = world:component() :: jecs.Entity<number>
 
@@ -93,15 +111,18 @@ const Health = world.component<number>();
 const Entity = world.entity();
 world.set(Entity, Health, 100);
 
-print(world.get(Entity, Health))
+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
@@ -112,6 +133,7 @@ function World:has(
 Example:
 
 ::: code-group
+
 ```luau [luau]
 local IsMoving = world:component()
 local Ragdolled = world:entity() -- This is a tag, meaning it won't contain data
@@ -155,9 +177,11 @@ print(world.has(Entity, Ragdolled));
 // nil
 // true
 ```
+
 :::
 
 ## 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
@@ -172,7 +196,9 @@ This function is idempotent, meaning if the entity already has the id, this oper
 :::
 
 ## set
+
 Adds or changes data in the entity's component.
+
 ```luau
 function World:set(
     entity: Entity, -- The entity
@@ -184,6 +210,7 @@ function World:set(
 Example:
 
 ::: code-group
+
 ```luau [luau]
 local Health = world:component() :: jecs.Entity<number>
 
@@ -206,19 +233,22 @@ const Health = world.component<number>();
 const Entity = world.entity();
 world.set(Entity, Health, 100);
 
-print(world.get(Entity, Health)) 
+print(world.get(Entity, Health));
 
 world.set(Entity, Health, 50);
-print(world.get(Entity, Health))
+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
@@ -228,6 +258,7 @@ function World: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
@@ -242,16 +273,20 @@ 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
+
 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
@@ -261,7 +296,9 @@ function World:target(
 ```
 
 ## 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
@@ -275,7 +312,9 @@ world:target(entity, jecs.ChildOf, 0)
 ```
 
 ## contains
+
 Checks if an entity or component (id) exists in the world.
+
 ```luau
 function World:contains(
     entity: Entity,
@@ -285,6 +324,7 @@ function World:contains(
 Example:
 
 ::: code-group
+
 ```luau [luau]
 local entity = world:entity()
 print(world:contains(entity))
@@ -308,10 +348,13 @@ print(world.contains(2));
 // true
 // false
 ```
+
 :::
 
 ## remove
+
 Removes a component (ID) from an entity
+
 ```luau
 function World:remove(
     entity: Entity,
@@ -322,6 +365,7 @@ function World:remove(
 Example:
 
 ::: code-group
+
 ```luau [luau]
 local IsMoving = world:component()
 
@@ -353,10 +397,13 @@ print(world.has(entity, IsMoving));
 // true
 // false
 ```
+
 :::
 
 ## delete
+
 Deletes an entity and all of its related components and relationships.
+
 ```luau
 function World:delete(
     entity: Entity
@@ -366,6 +413,7 @@ function World:delete(
 Example:
 
 ::: code-group
+
 ```luau [luau]
 local entity = world:entity()
 print(world:has(entity))
@@ -391,12 +439,62 @@ print(world.has(entity));
 // true
 // false
 ```
+
 :::
 
 ## clear
+
 Clears all of the components and relationships of the entity without deleting it.
+
 ```luau
 function World:clear(
     entity: Entity
 ): void
 ```
+
+## each
+
+Iterate over all entities with the specified component.
+Useful when you only need the entity for a specific ID and you want to avoid creating a query.
+
+```luau
+function World:each(
+	id: Entity -- The component ID
+): () -> Entity
+```
+
+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
+
+Iterate entities in root of parent
+
+```luau
+function World:children(
+	parent: Entity -- The parent entity
+): () -> Entity
+```
+
+This is the same as calling:
+
+```luau
+world:each(pair(ChildOf, parent))
+```

jecs.luau

@@ -1995,6 +1995,7 @@ local function world_each(world: World, id): () -> ()
 			archetype = archetypes[archetype_id]
 			entities = archetype.entities
 			row = #entities
+			entity = entities[row]
 		end
 		row -= 1
 		return entity

package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rbxts/jecs",
-	"version": "0.5.1",
+	"version": "0.5.2",
 	"description": "Stupidly fast Entity Component System",
 	"main": "jecs.luau",
 	"repository": {

test/tests.luau

@@ -900,20 +900,39 @@ end)
 
 TEST("world:children", function()
 	local world = world_new()
-	local e1 = world:entity()
+	local C = world:component()
-	local e2 = world:entity()
+	local T = world:entity()
-	local e3 = world:entity()
 
+	local e1 = world:entity()
+	world:set(e1, C, true)
+
+	local e2 = world:entity()
+
+	world:add(e2, T)
 	world:add(e2, pair(ChildOf, e1))
+
+	local e3 = world:entity()
 	world:add(e3, pair(ChildOf, e1))
 
-	for entity in world:children(pair(ChildOf, e1)) do
+	local count = 0
+	for entity in world:children(e1) do
+		count += 1
 		if entity == e2 or entity == e3 then
 			CHECK(true)
 			continue
 		end
 		CHECK(false)
 	end
+	CHECK(count == 2)
+
+	world:remove(e2, pair(ChildOf, e1))
+
+	count = 0
+	for entity in world:children(e1) do
+		count += 1
+	end
+
+	CHECK(count == 1)
 end)
 
 TEST("world:clear()", function()

wally.toml

@@ -1,6 +1,6 @@
 [package]
 name = "ukendio/jecs"
-version = "0.5.1"
+version = "0.5.2"
 registry = "https://github.com/UpliftGames/wally-index"
 realm = "shared"
 license = "MIT"