Add orderBy, order, and limit support to ForEach event

Adds optional ordering and limiting to ForEach events:
- orderBy: an expression evaluated for each instance to determine sort order
- order: "asc" (default) or "desc" direction for iteration
- limit: optional expression for max iterations (e.g., limit=1 picks highest/lowest)

Changes:
- Core C++ (ForEachEvent.h/.cpp): new fields with serialization
- GDevelop.js bindings: expose getters/setters for orderBy, order, limit
- GDJS codegen: sorting phase evaluates expression per instance, sorts indices,
  applies limit, then iterates in order. Unordered path unchanged.
- UI (ForEachEvent.js): select between "(any order)" and "ordered by" with
  expression field, asc/desc selector, and optional limit
- TextRenderer: display ordering info in text representation
- Tests: 12 integration tests covering simple/nested ForEach, orderBy with
  asc/desc, limits (1, 2, none), local variables, loop index, and groups

https://claude.ai/code/session_01LXTeNz7ehNS5TqFYSU6aw5

Author: claude

Core/GDCore/Events/Builtin/ForEachEvent.cpp

@@ -16,6 +16,9 @@ namespace gd {
 ForEachEvent::ForEachEvent()
     : BaseEvent(),
       objectsToPick(""),
+      orderBy(""),
+      order("asc"),
+      limit(""),
       variables(gd::VariablesContainer::SourceType::Local) {}
 
 vector<gd::InstructionsList*> ForEachEvent::GetAllConditionsVectors() {
@@ -85,6 +88,13 @@ void ForEachEvent::SerializeTo(SerializerElement& element) const {
   if (!loopIndexVariableName.empty()) {
     element.AddChild("loopIndexVariable").SetStringValue(loopIndexVariableName);
   }
+  if (!orderBy.GetPlainString().empty()) {
+    element.AddChild("orderBy").SetValue(orderBy.GetPlainString());
+    element.AddChild("order").SetStringValue(order);
+    if (!limit.GetPlainString().empty()) {
+      element.AddChild("limit").SetValue(limit.GetPlainString());
+    }
+  }
 }
 
 void ForEachEvent::UnserializeFrom(gd::Project& project,
@@ -111,6 +121,16 @@ void ForEachEvent::UnserializeFrom(gd::Project& project,
       element.HasChild("loopIndexVariable")
           ? element.GetChild("loopIndexVariable").GetStringValue()
           : "";
+
+  orderBy = element.HasChild("orderBy")
+                ? gd::Expression(element.GetChild("orderBy").GetValue().GetString())
+                : gd::Expression("");
+  order = element.HasChild("order")
+              ? element.GetChild("order").GetStringValue()
+              : "asc";
+  limit = element.HasChild("limit")
+              ? gd::Expression(element.GetChild("limit").GetValue().GetString())
+              : gd::Expression("");
 }
 
 }  // namespace gd

Core/GDCore/Events/Builtin/ForEachEvent.h

@@ -59,6 +59,23 @@ class GD_CORE_API ForEachEvent : public gd::BaseEvent {
   const gd::String& GetLoopIndexVariableName() const { return loopIndexVariableName; }
   void SetLoopIndexVariableName(const gd::String& name) { loopIndexVariableName = name; }
 
+  const gd::String& GetOrderBy() const {
+    return orderBy.GetPlainString();
+  };
+  void SetOrderBy(gd::String orderBy_) {
+    orderBy = gd::Expression(orderBy_);
+  };
+
+  const gd::String& GetOrder() const { return order; }
+  void SetOrder(const gd::String& order_) { order = order_; }
+
+  const gd::String& GetLimit() const {
+    return limit.GetPlainString();
+  };
+  void SetLimit(gd::String limit_) {
+    limit = gd::Expression(limit_);
+  };
+
   virtual std::vector<const gd::InstructionsList*> GetAllConditionsVectors()
       const;
   virtual std::vector<const gd::InstructionsList*> GetAllActionsVectors() const;
@@ -81,6 +98,9 @@ class GD_CORE_API ForEachEvent : public gd::BaseEvent {
   gd::EventsList events;
   VariablesContainer variables;
   gd::String loopIndexVariableName;
+  gd::Expression orderBy;
+  gd::String order;
+  gd::Expression limit;
 };
 
 }  // namespace gd

GDJS/GDJS/Extensions/Builtin/CommonInstructionsExtension.cpp

@@ -792,6 +792,8 @@ CommonInstructionsExtension::CommonInstructionsExtension() {
         for (unsigned int i = 0; i < realObjects.size(); ++i)
           parentContext.ObjectsListNeeded(realObjects[i]);
 
+        const bool hasOrderBy = !event.GetOrderBy().empty();
+
         // Context is "reset" each time the event is repeated (i.e. objects are
         // picked again)
         gd::EventsCodeGenerationContext context;
@@ -809,6 +811,25 @@ CommonInstructionsExtension::CommonInstructionsExtension() {
         for (unsigned int i = 0; i < realObjects.size(); ++i)
           context.EmptyObjectsListNeeded(realObjects[i]);
 
+        // When orderBy is set, we also need a sorting context to generate the
+        // expression code for evaluating the orderBy expression on each object.
+        gd::String orderByExpressionCode;
+        gd::String sortObjectDeclaration;
+        if (hasOrderBy) {
+          gd::EventsCodeGenerationContext sortContext;
+          sortContext.InheritsFrom(parentContext);
+          sortContext.ForbidReuse();
+          for (unsigned int i = 0; i < realObjects.size(); ++i)
+            sortContext.EmptyObjectsListNeeded(realObjects[i]);
+
+          orderByExpressionCode =
+              gd::ExpressionCodeGenerator::GenerateExpressionCode(
+                  codeGenerator, sortContext, "number",
+                  gd::Expression(event.GetOrderBy()));
+          sortObjectDeclaration =
+              codeGenerator.GenerateObjectsDeclarationCode(sortContext) + "\n";
+        }
+
         // Prepare conditions/actions codes
         gd::String conditionsCode = codeGenerator.GenerateConditionsListCode(
             event.GetConditions(), context);
@@ -845,12 +866,29 @@ CommonInstructionsExtension::CommonInstructionsExtension() {
               event.GetLoopIndexVariableName(), context);
         }
 
+        // Declare additional variables for the orderBy sorting phase
+        gd::String forEachSortedList;
+        gd::String forEachSortKeysList;
+        gd::String forEachLimitVar;
+        if (hasOrderBy) {
+          forEachSortedList =
+              codeGenerator.GetCodeNamespaceAccessor() + "forEachSorted" +
+              gd::String::From(context.GetContextDepth());
+          codeGenerator.AddGlobalDeclaration(forEachSortedList + " = [];\n");
+          forEachSortKeysList =
+              codeGenerator.GetCodeNamespaceAccessor() + "forEachSortKeys" +
+              gd::String::From(context.GetContextDepth());
+          codeGenerator.AddGlobalDeclaration(forEachSortKeysList + " = [];\n");
+          forEachLimitVar =
+              codeGenerator.GetCodeNamespaceAccessor() + "forEachLimit" +
+              gd::String::From(context.GetContextDepth());
+          codeGenerator.AddGlobalDeclaration(forEachLimitVar + " = 0;\n");
+        }
+
         outputCode += localVariablesInitializationCode;
 
-        if (realObjects.size() !=
-            1) //(We write a slightly more simple ( and optimized ) output code
-               // when only one object list is used.)
-        {
+        // --- Build the combined objects list ---
+        if (realObjects.size() != 1) {
           outputCode += forEachTotalCountVar + " = 0;\n";
           outputCode += forEachObjectsList + ".length = 0;\n";
           for (unsigned int i = 0; i < realObjects.size(); ++i) {
@@ -873,66 +911,196 @@ CommonInstructionsExtension::CommonInstructionsExtension() {
           }
         }
 
-        // Write final code :
+        if (hasOrderBy) {
+          // --- OrderBy sorting phase ---
+          // Build a combined list (always use forEachObjectsList for sorting)
+          if (realObjects.size() == 1) {
+            // For single object: copy to the combined list for uniform handling
+            outputCode += forEachObjectsList + ".length = 0;\n";
+            outputCode +=
+                forEachObjectsList + ".push.apply(" + forEachObjectsList +
+                "," +
+                codeGenerator.GetObjectListName(realObjects[0], parentContext) +
+                ");\n";
+            outputCode += forEachTotalCountVar + " = " + forEachObjectsList +
+                          ".length;\n";
+          }
 
-        // For loop declaration
-        if (realObjects.size() ==
-            1) // We write a slightly more simple ( and optimized ) output code
-               // when only one object list is used.
+          // Evaluate the orderBy expression for each object and store in sort keys
+          outputCode += forEachSortKeysList + ".length = 0;\n";
           outputCode +=
               "for (" + forEachIndexVar + " = 0;" + forEachIndexVar + " < " +
-              codeGenerator.GetObjectListName(realObjects[0], parentContext) +
-              ".length;++" + forEachIndexVar + ") {\n";
-        else
-          outputCode += "for (" + forEachIndexVar + " = 0;" + forEachIndexVar +
-                        " < " + forEachTotalCountVar + ";++" + forEachIndexVar +
-                        ") {\n";
-
-        // Empty object lists declaration
-        outputCode += objectDeclaration;
+              forEachTotalCountVar + ";++" + forEachIndexVar + ") {\n";
+
+          // Pick one object for evaluation
+          outputCode += sortObjectDeclaration;
+          for (unsigned int i = 0; i < realObjects.size(); ++i) {
+            if (realObjects.size() == 1) {
+              outputCode +=
+                  codeGenerator.GetObjectListName(realObjects[0], context) +
+                  ".push(" + forEachObjectsList + "[" + forEachIndexVar +
+                  "]);\n";
+            } else {
+              gd::String count;
+              for (unsigned int j = 0; j <= i; ++j) {
+                gd::String forEachCountVar =
+                    codeGenerator.GetCodeNamespaceAccessor() + "forEachCount" +
+                    gd::String::From(j) + "_" +
+                    gd::String::From(context.GetContextDepth());
+                if (j != 0)
+                  count += "+";
+                count += forEachCountVar;
+              }
+              if (i != 0)
+                outputCode += "else ";
+              outputCode +=
+                  "if (" + forEachIndexVar + " < " + count + ") {\n";
+              outputCode +=
+                  "    " +
+                  codeGenerator.GetObjectListName(realObjects[i], context) +
+                  ".push(" + forEachObjectsList + "[" + forEachIndexVar +
+                  "]);\n";
+              outputCode += "}\n";
+            }
+          }
+
+          outputCode += forEachSortKeysList + ".push(" +
+                        orderByExpressionCode + ");\n";
+          outputCode += "}\n"; // End of sort key evaluation loop
+
+          // Build sorted indices and sort them
+          outputCode += forEachSortedList + ".length = 0;\n";
+          outputCode += "for (" + forEachIndexVar + " = 0;" +
+                        forEachIndexVar + " < " + forEachTotalCountVar + ";++" +
+                        forEachIndexVar + ") " + forEachSortedList + ".push(" +
+                        forEachIndexVar + ");\n";
 
-        // Pick one object
-        if (realObjects.size() == 1) {
-          // We write a slightly more simple ( and optimized ) output code
-          // when only one object list is used.
-          gd::String temporary = codeGenerator.GetCodeNamespaceAccessor() +
-                                 "forEachTemporary" +
-                                 gd::String::From(context.GetContextDepth());
-          codeGenerator.AddGlobalDeclaration(temporary + " = null;\n");
+          gd::String isDesc =
+              event.GetOrder() == "desc" ? "true" : "false";
           outputCode +=
-              temporary + " = " +
-              codeGenerator.GetObjectListName(realObjects[0], parentContext) +
-              "[" + forEachIndexVar + "];\n";
+              forEachSortedList + ".sort(function(a, b) { return " + isDesc +
+              " ? " + forEachSortKeysList + "[b] - " + forEachSortKeysList +
+              "[a] : " + forEachSortKeysList + "[a] - " +
+              forEachSortKeysList + "[b]; });\n";
+
+          // Apply limit
+          const bool hasLimit = !event.GetLimit().empty();
+          if (hasLimit) {
+            gd::String limitCode =
+                gd::ExpressionCodeGenerator::GenerateExpressionCode(
+                    codeGenerator, parentContext, "number",
+                    gd::Expression(event.GetLimit()));
+            outputCode += forEachLimitVar + " = " + limitCode + ";\n";
+            outputCode += "if (" + forEachLimitVar + " > 0 && " +
+                          forEachSortedList + ".length > " + forEachLimitVar +
+                          ") " + forEachSortedList + ".length = " +
+                          forEachLimitVar + ";\n";
+          }
 
+          // Iterate through sorted indices
           outputCode +=
-              codeGenerator.GetObjectListName(realObjects[0], context) +
-              ".push(" + temporary + ");\n";
-        } else {
-          // Generate the code to pick only one object in the lists
+              "for (" + forEachIndexVar + " = 0;" + forEachIndexVar + " < " +
+              forEachSortedList + ".length;++" + forEachIndexVar + ") {\n";
+
+          // Empty object lists and pick the right object
+          outputCode += objectDeclaration;
           for (unsigned int i = 0; i < realObjects.size(); ++i) {
-            gd::String count;
-            for (unsigned int j = 0; j <= i; ++j) {
-              gd::String forEachCountVar =
-                  codeGenerator.GetCodeNamespaceAccessor() + "forEachCount" +
-                  gd::String::From(j) + "_" +
+            if (realObjects.size() == 1) {
+              gd::String temporary =
+                  codeGenerator.GetCodeNamespaceAccessor() +
+                  "forEachTemporary" +
                   gd::String::From(context.GetContextDepth());
-
-              if (j != 0)
-                count += "+";
-              count += forEachCountVar;
+              codeGenerator.AddGlobalDeclaration(temporary + " = null;\n");
+              outputCode +=
+                  temporary + " = " + forEachObjectsList + "[" +
+                  forEachSortedList + "[" + forEachIndexVar + "]];\n";
+              outputCode +=
+                  codeGenerator.GetObjectListName(realObjects[0], context) +
+                  ".push(" + temporary + ");\n";
+            } else {
+              gd::String count;
+              for (unsigned int j = 0; j <= i; ++j) {
+                gd::String forEachCountVar =
+                    codeGenerator.GetCodeNamespaceAccessor() + "forEachCount" +
+                    gd::String::From(j) + "_" +
+                    gd::String::From(context.GetContextDepth());
+                if (j != 0)
+                  count += "+";
+                count += forEachCountVar;
+              }
+              if (i != 0)
+                outputCode += "else ";
+              outputCode += "if (" + forEachSortedList + "[" + forEachIndexVar +
+                            "] < " + count + ") {\n";
+              outputCode +=
+                  "    " +
+                  codeGenerator.GetObjectListName(realObjects[i], context) +
+                  ".push(" + forEachObjectsList + "[" + forEachSortedList +
+                  "[" + forEachIndexVar + "]]);\n";
+              outputCode += "}\n";
             }
+          }
+        } else {
+          // --- Standard (no orderBy) path ---
+
+          // For loop declaration
+          if (realObjects.size() == 1)
+            outputCode +=
+                "for (" + forEachIndexVar + " = 0;" + forEachIndexVar + " < " +
+                codeGenerator.GetObjectListName(realObjects[0], parentContext) +
+                ".length;++" + forEachIndexVar + ") {\n";
+          else
+            outputCode +=
+                "for (" + forEachIndexVar + " = 0;" + forEachIndexVar + " < " +
+                forEachTotalCountVar + ";++" + forEachIndexVar + ") {\n";
+
+          // Empty object lists declaration
+          outputCode += objectDeclaration;
+
+          // Pick one object
+          if (realObjects.size() == 1) {
+            gd::String temporary =
+                codeGenerator.GetCodeNamespaceAccessor() +
+                "forEachTemporary" +
+                gd::String::From(context.GetContextDepth());
+            codeGenerator.AddGlobalDeclaration(temporary + " = null;\n");
+            outputCode +=
+                temporary + " = " +
+                codeGenerator.GetObjectListName(realObjects[0], parentContext) +
+                "[" + forEachIndexVar + "];\n";
 
-            if (i != 0)
-              outputCode += "else ";
-            outputCode += "if (" + forEachIndexVar + " < " + count + ") {\n";
             outputCode +=
-                "    " +
-                codeGenerator.GetObjectListName(realObjects[i], context) +
-                ".push(" + forEachObjectsList + "[" + forEachIndexVar + "]);\n";
-            outputCode += "}\n";
+                codeGenerator.GetObjectListName(realObjects[0], context) +
+                ".push(" + temporary + ");\n";
+          } else {
+            for (unsigned int i = 0; i < realObjects.size(); ++i) {
+              gd::String count;
+              for (unsigned int j = 0; j <= i; ++j) {
+                gd::String forEachCountVar =
+                    codeGenerator.GetCodeNamespaceAccessor() + "forEachCount" +
+                    gd::String::From(j) + "_" +
+                    gd::String::From(context.GetContextDepth());
+
+                if (j != 0)
+                  count += "+";
+                count += forEachCountVar;
+              }
+
+              if (i != 0)
+                outputCode += "else ";
+              outputCode +=
+                  "if (" + forEachIndexVar + " < " + count + ") {\n";
+              outputCode +=
+                  "    " +
+                  codeGenerator.GetObjectListName(realObjects[i], context) +
+                  ".push(" + forEachObjectsList + "[" + forEachIndexVar +
+                  "]);\n";
+              outputCode += "}\n";
+            }
           }
         }
 
+        // --- Common iteration body (both ordered and unordered) ---
         if (hasIndexVariable) {
           outputCode +=
               indexVariableAccessor + ".setNumber(" + forEachIndexVar + ");\n";

GDevelop.js/Bindings/Bindings.idl

@@ -2518,6 +2518,12 @@ interface ForEachEvent {
     [Ref] InstructionsList GetActions();
     [Const, Ref] DOMString GetLoopIndexVariableName();
     void SetLoopIndexVariableName([Const] DOMString name);
+    [Const, Ref] DOMString GetOrderBy();
+    void SetOrderBy([Const] DOMString orderBy);
+    [Const, Ref] DOMString GetOrder();
+    void SetOrder([Const] DOMString order);
+    [Const, Ref] DOMString GetLimit();
+    void SetLimit([Const] DOMString limit);
 };
 ForEachEvent implements BaseEvent;