From f57bf543476eeac6e82dc5ac0b85074ebd591e54 Mon Sep 17 00:00:00 2001
From: 4ian <1280130+4ian@users.noreply.github.com>
Date: Mon, 2 Mar 2026 08:24:44 +0000
Subject: [PATCH] [Auto] [Update] Document For Each event ordering by
 expression and limit features

---
 automated_updates_data.json            |  2 +-
 docs/gdevelop5/events/foreach/index.md | 12 ++++++++++++
 2 files changed, 13 insertions(+), 1 deletion(-)

diff --git a/automated_updates_data.json b/automated_updates_data.json
index c6d8df7148..20604f84e8 100644
--- a/automated_updates_data.json
+++ b/automated_updates_data.json
@@ -1,5 +1,5 @@
 {
-  "last_automated_updates_commit": "ec5dc8937205cd8e1b9bdedb434a19da1b822613",
+  "last_automated_updates_commit": "c4cca8e3426ac08aaf4be9e77bb524bd51bf01e7",
   "last_improved_things": [
     {
       "date": "2026-02-16",
diff --git a/docs/gdevelop5/events/foreach/index.md b/docs/gdevelop5/events/foreach/index.md
index 7328a762af..2ef8bb1f0c 100644
--- a/docs/gdevelop5/events/foreach/index.md
+++ b/docs/gdevelop5/events/foreach/index.md
@@ -19,6 +19,18 @@ For Each events can have a **loop counter variable**. When set, this variable st
 
 To add a loop counter variable, right-click on the For Each event and choose **Add > Loop Counter Variable**.
 
+## Ordering instances
+
+By default, the For Each event iterates over instances in the **default order** (the internal engine order). You can change this by choosing **ordered by** in the event, which lets you specify a numeric expression to sort instances before iterating. The sort can be **ascending** or **descending**.
+
+Common use cases:
+
+- Process enemies by distance to the player: `Enemy.Distance(Player)` (ascending, nearest first)
+- Handle objects by a variable value: `Enemy.SomeVariable` (descending, highest first)
+- Act on the object with the highest health first using a behavior expression
+
+An optional **limit** can be set to only process the first N instances after sorting. For example, order by distance and limit to 3 to only process the 3 nearest enemies.
+
 ## How to add this event
 
 Right click (or long press) on an existing [event](/gdevelop5/events) and choose *"Add"* in the menu. Then, select the event you want to add.