[Auto] [Update] Document For Each event ordering by expression and limit features

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",

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.