From 7824c1aa5565e8f5f7252e36d9db5efa39231a37 Mon Sep 17 00:00:00 2001
From: kurokuukyo <github@kurokuukyo.com>
Date: Tue, 21 Apr 2026 14:23:11 -0400
Subject: [PATCH] docs for world:targets

---
 how_to/042_target.luau | 9 +++++++++
 src/jecs.d.ts          | 8 ++++++++
 2 files changed, 17 insertions(+)

diff --git a/how_to/042_target.luau b/how_to/042_target.luau
index 50d8b3a..1a57815 100644
--- a/how_to/042_target.luau
+++ b/how_to/042_target.luau
@@ -6,6 +6,10 @@
 	Use target when you have queried with a wildcard (e.g. pair(Eats, jecs.Wildcard))
 	and need the actual target entity for each result. Without an index, the
 	default is 0 (the first target).
+
+	world:targets(entity, relation) returns an iterator for all targets of a relation.
+	
+	Use targets when you need to get every possible target for all indexes.
 ]]
 
 local jecs = require("@jecs")
@@ -35,3 +39,8 @@ print(third == nil)  -- true
 -- Omitting the index is the same as index 0
 local default = world:target(bob, Eats)
 print(default == Apples)  -- true
+
+-- Iterates through all targets
+for target in world:targets(bob, Eats) do
+	print(target)
+end
diff --git a/src/jecs.d.ts b/src/jecs.d.ts
index e2de9d6..b13d118 100755
--- a/src/jecs.d.ts
+++ b/src/jecs.d.ts
@@ -155,6 +155,14 @@ export class World {
 	 */
 	target(entity: Entity, relation: Entity, index?: number): Entity | undefined;
 
+	/**
+	 * Gets an iterator for all targets of a relationship.
+	 * Returns an empty iterator if no matches are found.
+	 * @param entity The entity using a relationship pair.
+	 * @param relation The "relationship" component/tag
+	 */
+	targets(entity: Entity, relation: Entity): Iter<Entity>
+
 	/**
 	 * Deletes an entity (and its components/relationships) from the world entirely.
 	 * @param entity The entity to delete.